react-dockable-desktop 7.7.3 → 7.8.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 +91 -1
- package/README.md +7 -4
- package/STABILITY.md +89 -0
- package/dist/index.cjs +6 -6
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +45 -6
- package/dist/index.d.ts +45 -6
- package/dist/index.js +6 -6
- package/dist/index.js.map +1 -1
- package/dist/styles.css +7 -0
- package/package.json +6 -2
package/CHANGELOG.md
CHANGED
|
@@ -3,9 +3,91 @@
|
|
|
3
3
|
All notable changes to this project will be documented in this file.
|
|
4
4
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
5
5
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
6
|
+
What counts as the public API, how long a deprecated API keeps working and how long an old major
|
|
7
|
+
version is supported are in [STABILITY.md](STABILITY.md). Entries group changes under **Breaking**,
|
|
8
|
+
**Added**, **Changed**, **Deprecated**, **Removed** and **Fixed**; **Deprecated** names each
|
|
9
|
+
replacement and the version that removes the old API.
|
|
6
10
|
|
|
7
11
|
## [Unreleased]
|
|
8
12
|
|
|
13
|
+
## [7.8.0] — 2026-10-06
|
|
14
|
+
|
|
15
|
+
More control over how the desktop looks and where panels open, all opt-in: without the new options,
|
|
16
|
+
nothing changes. The API check confirms every change is an addition.
|
|
17
|
+
|
|
18
|
+
### Added
|
|
19
|
+
|
|
20
|
+
- **Your own empty-workspace view.** `<RddDesktop emptyWorkspace={<Welcome />}>` shows your element
|
|
21
|
+
while no panel is docked, in place of the built-in "Empty Workspace Section" message: a welcome
|
|
22
|
+
screen, a logo, "Open a file" buttons. Floating windows still show over it, and a window can still
|
|
23
|
+
be dropped onto it to dock. Other empty groups in a split keep the built-in message.
|
|
24
|
+
- **Open a panel beside another.** `openPanel(id, component, { dockTo: { panel, position, size } })`
|
|
25
|
+
docks a new panel as a tab in that panel's group (`position: 'center'`) or in a new group split off
|
|
26
|
+
on one side, taking `size` (0.1–0.9) of the split. It wins over `initialTarget`. If the target
|
|
27
|
+
panel isn't docked, the new panel is placed as usual, with a development warning.
|
|
28
|
+
- **State attributes for your CSS.** Tabs carry `data-rdd-selected` (shown in their group),
|
|
29
|
+
`data-rdd-focused` (the workspace's active panel) and `data-rdd-dirty`; floating windows carry
|
|
30
|
+
`data-rdd-focused` and `data-rdd-maximized`. Each is present only while it is true, so
|
|
31
|
+
`[data-rdd-dirty]` styles unsaved panels without relying on internal class names. The existing
|
|
32
|
+
classes are unchanged.
|
|
33
|
+
- **Per-panel-type classes.** `className` and `tabClassName` in a panel type's `defaultOptions`
|
|
34
|
+
add your class to every panel of that type (on its content element, which moves with it) and to
|
|
35
|
+
its tab.
|
|
36
|
+
- **`keepAlive: false`**, per panel type: the component unmounts while the panel is an unselected
|
|
37
|
+
tab or minimized, and mounts afresh when shown, to free what a heavy, rarely shown panel holds.
|
|
38
|
+
Its own state is lost each time; its tab, title and lifecycle continue, and `onClose` is called
|
|
39
|
+
only when it is really closed. The taskbar shows a placeholder preview for it. The default is
|
|
40
|
+
unchanged: panels stay mounted and keep their state.
|
|
41
|
+
|
|
42
|
+
### Docs
|
|
43
|
+
|
|
44
|
+
- New page, **[Using it with MUI, Bootstrap or Tailwind](https://felipecarrillo100.github.io/react-dockable-desktop/guide/ui-frameworks)**:
|
|
45
|
+
dark-mode bridging for each, the z-index of the library's layers next to the frameworks', why a
|
|
46
|
+
framework popup opened inside one of the library's modals appears behind it and the two fixes,
|
|
47
|
+
resets, and the order to try when overriding styles.
|
|
48
|
+
- Theming: **Styling by state and by panel type**. Layout: **Opening beside another panel**. Panel
|
|
49
|
+
Registry: **Freeing a hidden panel**. The `openPanel` options, `RddDesktop` props and
|
|
50
|
+
`defaultOptions` tables list the new options.
|
|
51
|
+
|
|
52
|
+
### Tests
|
|
53
|
+
|
|
54
|
+
- `ReleaseA.test.tsx` (15 tests): the empty view (shown and gone as panels dock and close; a
|
|
55
|
+
floating window can still dock into it), the state attributes on tabs and windows, `dockTo`
|
|
56
|
+
(sides, centre, size clamping, winning over `initialTarget`, the fallback and its warning, no
|
|
57
|
+
effect on an open panel), the per-type classes (also after floating), and `keepAlive: false`
|
|
58
|
+
(unmount and fresh remount, no `onClose` on hide, the placeholder preview, the default
|
|
59
|
+
unchanged, and no leak over 50 hide/show cycles). Each was seen failing with its feature broken.
|
|
60
|
+
|
|
61
|
+
## [7.7.4] — 2026-10-06
|
|
62
|
+
|
|
63
|
+
A written stability policy, and CI that enforces it. No API or behaviour change.
|
|
64
|
+
|
|
65
|
+
### Added
|
|
66
|
+
|
|
67
|
+
- **[STABILITY.md](STABILITY.md)**, also on the docs site as *Stability & Versioning*: what the
|
|
68
|
+
public API is (the exports with their full signatures, the two entry points, and layouts saved by
|
|
69
|
+
7.x), what each kind of release may change, deprecation (an alias marked `@deprecated` that warns
|
|
70
|
+
once in development, kept for at least one minor release and three months, removed only in a
|
|
71
|
+
major, and a codemod for every rename), bug fixes for the previous major for 12 months after the
|
|
72
|
+
next one ships, and at most one or two majors a year.
|
|
73
|
+
- **The API report is the contract.** `api/react-dockable-desktop.api.md` is generated by
|
|
74
|
+
[API Extractor](https://api-extractor.com/) from the published type declarations
|
|
75
|
+
(`npm run api:report`), so every change to a signature shows as a diff in review.
|
|
76
|
+
`npm run api:check` runs in CI: the committed report must match the build, and a removed
|
|
77
|
+
declaration, a removed member or a changed signature since the last release fails unless the
|
|
78
|
+
major version went up. 7.7.4 is the first release with a report, so the check compares against
|
|
79
|
+
it from the next release on.
|
|
80
|
+
|
|
81
|
+
### Internal
|
|
82
|
+
|
|
83
|
+
- `LayoutGridNode.orientation`'s doc comment read "Split orientation orientation indicator"; it now
|
|
84
|
+
says what each value does.
|
|
85
|
+
- Five TSDoc links pointed at names that don't exist (`{@link Sidebar}`, the pre-7.0 name, and
|
|
86
|
+
workspace methods without their interface); they now resolve.
|
|
87
|
+
- `warnDeprecated()`, the development-only, once-per-name warning a deprecated alias calls.
|
|
88
|
+
- A saved-layout fixture written by 7.7.3's own `saveLayout()` (a split, panel props, a
|
|
89
|
+
`dedupeKey`, a descriptor title, an anchored window, a minimized panel), next to the 6.4.0 one.
|
|
90
|
+
|
|
9
91
|
## [7.7.3] — 2026-10-06
|
|
10
92
|
|
|
11
93
|
Code-health release: the lint gate checks the library again, dead code is checked too, and the
|
|
@@ -567,6 +649,12 @@ Fixes found by a consumer migrating a 30-file app from 6.4.0 with the 7.0.0 migr
|
|
|
567
649
|
|
|
568
650
|
A clean break: the public API takes the names the Vue and Angular ports of this library use, the workspace becomes a store that is live before anything mounts, and the stylesheet stops styling the host page. Nothing is deprecated first — every old name is gone, so the TypeScript compiler finds every call site. **Migration guide: [docs-site/guide/migration.md](https://felipecarrillo100.github.io/react-dockable-desktop/guide/migration#v6-x-→-v7-0-0)** — written so it can be applied by an automated agent in one pass; this release was accepted by having an agent migrate the four demo apps and a fixture app with the guide alone.
|
|
569
651
|
|
|
652
|
+
> **Why so much broke at once** (note added 2026-10-06). This release renamed most of the public
|
|
653
|
+
> API in one go, with no deprecation period, so that the React, Vue and Angular editions of this
|
|
654
|
+
> library share one vocabulary. That was a one-time cost, and it won't be repeated: from 7.0.0 on,
|
|
655
|
+
> an API is deprecated before it is removed, and removed only in a major version. See
|
|
656
|
+
> [STABILITY.md](STABILITY.md).
|
|
657
|
+
|
|
570
658
|
### Breaking
|
|
571
659
|
- **React 18 or later.** The peer range said 16.8; the library already relied on React 18 APIs.
|
|
572
660
|
- **`createWorkspace()` replaces `new WorkspaceClient()`.** The workspace is a store that exists on its own: calls made before a `<DockableDesktopProvider>` mounts apply immediately (the queue and `_connect()` are gone). `<DockableDesktopProvider workspace={…}>` replaces `client={…}`; `messages` replaces `predefinedMessages`, in the workspace config and on the provider.
|
|
@@ -1018,7 +1106,9 @@ All of the above is additive and backward-compatible: every new field is optiona
|
|
|
1018
1106
|
|
|
1019
1107
|
---
|
|
1020
1108
|
|
|
1021
|
-
[Unreleased]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.
|
|
1109
|
+
[Unreleased]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.8.0...HEAD
|
|
1110
|
+
[7.8.0]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.7.4...v7.8.0
|
|
1111
|
+
[7.7.4]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.7.3...v7.7.4
|
|
1022
1112
|
[7.7.3]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.7.2...v7.7.3
|
|
1023
1113
|
[7.7.2]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.7.1...v7.7.2
|
|
1024
1114
|
[7.7.1]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.7.0...v7.7.1
|
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# React Dockable Desktop
|
|
2
2
|
|
|
3
|
-
[](https://www.npmjs.com/package/react-dockable-desktop)
|
|
4
4
|
[](https://www.typescriptlang.org/)
|
|
5
5
|
[](#touch--mobile)
|
|
6
6
|
[](#license)
|
|
@@ -28,12 +28,13 @@ serialised layout format**, so a layout saved by either library loads in the oth
|
|
|
28
28
|
- **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
29
|
- **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
30
|
- **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
|
|
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 (a heavy, rarely shown panel type can opt out with `keepAlive: false`)
|
|
32
32
|
- **i18n & RTL** — full Right-to-Left layout support; `dir="rtl"` flips every control, tab order, and drop zone automatically
|
|
33
33
|
- **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
|
|
34
|
+
- **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
35
|
- **Layout Serialization** — save and restore the full workspace as a JSON string; survives page reloads
|
|
36
36
|
- **7 Built-in Skins** — VSCode, macOS, Chrome, Slate, Nord, Obsidian, Tokyo — all fully themeable via CSS variables
|
|
37
|
+
- **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
38
|
- **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
39
|
- **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
40
|
- **Zero extra dependencies** — no runtime dependencies beyond React itself; everything is bundled in
|
|
@@ -436,7 +437,7 @@ Every release is documented in one place — see the
|
|
|
436
437
|
**[CHANGELOG](https://github.com/felipecarrillo100/react-dockable-desktop/blob/main/CHANGELOG.md)**
|
|
437
438
|
for the full, up-to-date history of additions, fixes, and breaking changes.
|
|
438
439
|
|
|
439
|
-
Upgrading across a major version? See the [Migration Guide](https://felipecarrillo100.github.io/react-dockable-desktop/guide/migration).
|
|
440
|
+
Upgrading across a major version? See the [Migration Guide](https://felipecarrillo100.github.io/react-dockable-desktop/guide/migration). What may change in which release is in [STABILITY.md](STABILITY.md).
|
|
440
441
|
|
|
441
442
|
---
|
|
442
443
|
|
|
@@ -462,6 +463,8 @@ Complete guides, API reference, and interactive demo at:
|
|
|
462
463
|
| [Panel Overlay](https://felipecarrillo100.github.io/react-dockable-desktop/guide/panel-overlay) | `RddPanelOverlay`, panel toolbars, `RddFloatingWidget`, `useFloatingWidgets` |
|
|
463
464
|
| [Toast Notifications](https://felipecarrillo100.github.io/react-dockable-desktop/guide/toast) | `toast` singleton, `<RddToasts>`, queue behaviour, theming, `ToastAdapter` |
|
|
464
465
|
| [Migration Guide](https://felipecarrillo100.github.io/react-dockable-desktop/guide/migration) | Upgrading across major versions |
|
|
466
|
+
| [UI Frameworks](https://felipecarrillo100.github.io/react-dockable-desktop/guide/ui-frameworks) | Using it with MUI, Bootstrap or Tailwind: dark mode, z-index, overrides |
|
|
467
|
+
| [Stability & Versioning](https://felipecarrillo100.github.io/react-dockable-desktop/guide/stability) | What the public API is, deprecation and support periods |
|
|
465
468
|
| [API Reference](https://felipecarrillo100.github.io/react-dockable-desktop/api/) | Full type-level reference for all exports |
|
|
466
469
|
|
|
467
470
|
---
|
package/STABILITY.md
ADDED
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
# Stability and versioning
|
|
2
|
+
|
|
3
|
+
react-dockable-desktop follows [Semantic Versioning](https://semver.org/). This page says exactly
|
|
4
|
+
what that promises: what counts as the public API, what each kind of release may change, how long a
|
|
5
|
+
deprecated API keeps working, and how long an old major version is supported.
|
|
6
|
+
|
|
7
|
+
## Why 7.0.0 broke so much, and why it won't happen again
|
|
8
|
+
|
|
9
|
+
7.0.0 renamed most of the public API in one release, with no deprecation period. That was a
|
|
10
|
+
one-time cost: the React, Vue and Angular editions of this library (react-dockable-desktop,
|
|
11
|
+
vue-dockable-desktop and angular-dockable-desktop) now share one vocabulary, so a concept has the
|
|
12
|
+
same name in all three and a team can move between them. Since 7.0.0, the rules below apply to
|
|
13
|
+
every release, and a rename of that kind will not happen again.
|
|
14
|
+
|
|
15
|
+
## The public API
|
|
16
|
+
|
|
17
|
+
A breaking change to anything in this list needs a new major version.
|
|
18
|
+
|
|
19
|
+
- **The exports of `react-dockable-desktop`, with their full type signatures**: components, hooks,
|
|
20
|
+
functions, classes, constants and types. They are recorded in
|
|
21
|
+
[`api/react-dockable-desktop.api.md`](https://github.com/felipecarrillo100/react-dockable-desktop/blob/main/api/react-dockable-desktop.api.md),
|
|
22
|
+
which is generated from the published type declarations. That file is the contract: every change
|
|
23
|
+
to it shows as a diff in review, and CI rejects a removed or changed signature unless the major
|
|
24
|
+
version goes up.
|
|
25
|
+
- **The two entry points**: `react-dockable-desktop` and `react-dockable-desktop/styles.css`.
|
|
26
|
+
- **Saved layouts.** A layout saved by `saveLayout()` in any 7.x release loads with `loadLayout()`
|
|
27
|
+
(or `initialState`) in every later 7.x release. Fixtures written by the real `saveLayout()` are
|
|
28
|
+
part of the test suite, and each release that changes the format adds one. A new major version
|
|
29
|
+
states in its migration guide whether it reads the previous major's layouts.
|
|
30
|
+
|
|
31
|
+
### Not covered
|
|
32
|
+
|
|
33
|
+
These may change in a minor release. Every such change is listed in the
|
|
34
|
+
[CHANGELOG](https://github.com/felipecarrillo100/react-dockable-desktop/blob/main/CHANGELOG.md):
|
|
35
|
+
|
|
36
|
+
- Styling: the `--rdd-*` CSS custom properties, the `.rdd-*` class names, the `data-rdd-*`
|
|
37
|
+
attributes and the DOM structure. Tests pin the parts the stylesheet relies on, but they are not
|
|
38
|
+
yet part of this promise.
|
|
39
|
+
- Defaults: sizes, spacing, colours, animation timings, default labels. Changing a default, such
|
|
40
|
+
as a padding, is a minor release with a CHANGELOG note.
|
|
41
|
+
- Anything marked `@internal` or not exported, including `Workspace._core`.
|
|
42
|
+
- The wording of development-only console warnings.
|
|
43
|
+
|
|
44
|
+
## What each kind of release may do
|
|
45
|
+
|
|
46
|
+
| Release | May contain |
|
|
47
|
+
|---|---|
|
|
48
|
+
| **Major** (8.0.0) | Breaking changes to the public API, batched together, each with a migration note. Removes only APIs that were deprecated first. |
|
|
49
|
+
| **Minor** (7.8.0) | New APIs, new options, deprecations, changed defaults and visual changes, each with a CHANGELOG note. |
|
|
50
|
+
| **Patch** (7.7.4) | Bug fixes. |
|
|
51
|
+
|
|
52
|
+
A major version breaks nothing outside the public API, and nothing in it that wasn't deprecated
|
|
53
|
+
first.
|
|
54
|
+
|
|
55
|
+
## Deprecation
|
|
56
|
+
|
|
57
|
+
When an API is replaced:
|
|
58
|
+
|
|
59
|
+
1. The old name stays, as an alias of the new one, marked `@deprecated` in its documentation (your
|
|
60
|
+
editor shows it struck through), with the replacement and the version that removes it.
|
|
61
|
+
2. In development builds it prints one console warning, once per page load, naming the
|
|
62
|
+
replacement. Production builds print nothing.
|
|
63
|
+
3. The CHANGELOG entry of that release lists it under **Deprecated**.
|
|
64
|
+
4. It keeps working for **at least one minor release and at least three months**, and is removed
|
|
65
|
+
only in a major version.
|
|
66
|
+
5. A rename ships with a **codemod**: a [jscodeshift](https://github.com/facebook/jscodeshift)
|
|
67
|
+
script, so the migration is one command:
|
|
68
|
+
`npx jscodeshift -t <codemod URL from the CHANGELOG> src/`.
|
|
69
|
+
|
|
70
|
+
## Support for older major versions
|
|
71
|
+
|
|
72
|
+
The previous major version gets bug fixes for **12 months** after the next one ships: 7.x until 12
|
|
73
|
+
months after 8.0.0. Fixes only, no new features.
|
|
74
|
+
|
|
75
|
+
## How often major versions ship
|
|
76
|
+
|
|
77
|
+
At most **one or two a year**, with breaking changes batched into them rather than spread over
|
|
78
|
+
releases. The deprecations a major version will remove ship in a 7.x minor release first, so you
|
|
79
|
+
can move to the new APIs at your own pace before upgrading.
|
|
80
|
+
|
|
81
|
+
## How it is enforced
|
|
82
|
+
|
|
83
|
+
- **API report.** `npm run api:check` runs in CI on every push: the committed API report must match
|
|
84
|
+
the built type declarations, and a removed declaration, a removed member or a changed signature
|
|
85
|
+
since the last release fails the build unless the major version went up.
|
|
86
|
+
- **Exports.** A test pins every runtime and type export by name.
|
|
87
|
+
- **Saved layouts.** Fixture layouts written by earlier releases must load and save back unchanged.
|
|
88
|
+
- **Migration guide.** A sample 6.x app migrated with the 7.0 guide alone keeps compiling against
|
|
89
|
+
the current API.
|