react-dockable-desktop 7.7.2 → 7.7.4

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
@@ -3,9 +3,88 @@
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.7.4] — 2026-10-06
14
+
15
+ A written stability policy, and CI that enforces it. No API or behaviour change.
16
+
17
+ ### Added
18
+
19
+ - **[STABILITY.md](STABILITY.md)**, also on the docs site as *Stability & Versioning*: what the
20
+ public API is (the exports with their full signatures, the two entry points, and layouts saved by
21
+ 7.x), what each kind of release may change, deprecation (an alias marked `@deprecated` that warns
22
+ once in development, kept for at least one minor release and three months, removed only in a
23
+ major, and a codemod for every rename), bug fixes for the previous major for 12 months after the
24
+ next one ships, and at most one or two majors a year.
25
+ - **The API report is the contract.** `api/react-dockable-desktop.api.md` is generated by
26
+ [API Extractor](https://api-extractor.com/) from the published type declarations
27
+ (`npm run api:report`), so every change to a signature shows as a diff in review.
28
+ `npm run api:check` runs in CI: the committed report must match the build, and a removed
29
+ declaration, a removed member or a changed signature since the last release fails unless the
30
+ major version went up. 7.7.4 is the first release with a report, so the check compares against
31
+ it from the next release on.
32
+
33
+ ### Internal
34
+
35
+ - `LayoutGridNode.orientation`'s doc comment read "Split orientation orientation indicator"; it now
36
+ says what each value does.
37
+ - Five TSDoc links pointed at names that don't exist (`{@link Sidebar}`, the pre-7.0 name, and
38
+ workspace methods without their interface); they now resolve.
39
+ - `warnDeprecated()`, the development-only, once-per-name warning a deprecated alias calls.
40
+ - A saved-layout fixture written by 7.7.3's own `saveLayout()` (a split, panel props, a
41
+ `dedupeKey`, a descriptor title, an anchored window, a minimized panel), next to the 6.4.0 one.
42
+
43
+ ## [7.7.3] — 2026-10-06
44
+
45
+ Code-health release: the lint gate checks the library again, dead code is checked too, and the
46
+ library is at zero ESLint warnings. No API change and no intended behaviour change; the published
47
+ type declarations are byte-identical to 7.7.2.
48
+
49
+ ### Internal
50
+
51
+ - **`npm run lint` checks something again.** It ran `tsc --noEmit` against a `tsconfig.json` that
52
+ lists no files, so it passed whatever the code contained; that is how a 7.7.2 type error reached
53
+ `main`. It now type-checks the library source (`tsconfig.lib.json`: `src` without its tests) and
54
+ runs ESLint on `src`, tests included, and fails on any error. CI already ran `npm run lint`.
55
+ - **ESLint config for a library.** `react-refresh/only-export-components` is off for `src` (a
56
+ Vite dev-server rule for apps); a leading `_` marks a deliberately unused name; tests may use
57
+ `any`, `@ts-ignore` and module-level counters. `no-explicit-any` and the React Compiler rules
58
+ (`react-hooks/refs`, `globals`, `immutability`, `set-state-in-effect`) are warnings for now: 59
59
+ remain in library code. The 17 errors left were fixed, among them 13 unused imports and
60
+ variables in tests.
61
+ - **CI installs with `npm ci` on Node 24.** `npm ci` failed on Node 20's npm 10, which resolves this
62
+ lockfile's peer dependencies differently; npm 11 and 12 accept it unchanged. Node 20 is past its
63
+ end of life.
64
+ - `recycle_bin/` deleted (7 files, unused since August).
65
+ - **Dead code is checked too.** `npm run lint` also runs [knip](https://knip.dev) (`knip.json`), which
66
+ reports unused files, exports and dependencies across the library, the demos, the tests and the
67
+ scripts. Its first run found little dead code in the library: three default exports nothing
68
+ imports (`DockableDesktopProvider`, `PanelRegistry`, `Sidebar`; the named exports remain) and
69
+ the unused `copyfiles` dev dependency, all removed. The published type declarations are
70
+ byte-identical.
71
+ - **ESLint: zero warnings, and warnings now fail the lint too** (`--max-warnings 0`).
72
+ `no-explicit-any` and the React Compiler rules are errors again. The published type
73
+ declarations are byte-identical.
74
+ - **`any`:** the internal ones got real types (the event bus, the layout parser, the taskbar
75
+ preview, overlay and registry casts). The public ones stay `any` with a reason beside each,
76
+ because `unknown` would break users' code: event payloads, `ComponentType<any>` in the panel
77
+ and overlay registries, overlay `props`, and the dialogs' message `values` (narrowed with the
78
+ title type in 8.0.0).
79
+ - **Refs written during render** (the "latest value" pattern, 16 places) now go through
80
+ `useLatestRef`, which updates the ref in an insertion effect. That runs before every layout
81
+ effect of the commit, so a child's effect never reads the previous value; a test pins it,
82
+ and fails with a layout effect. `panelMount` captures the initial container type with
83
+ `useState` instead of a ref read during render.
84
+ - **Four deliberate patterns** keep a disable comment that gives the reason: two effects that
85
+ must set state (the drawer closing when its tab disappears notifies a controlling parent),
86
+ an unmount cleanup that reads the pending timer, and the panel handle's `[id]` dependency.
87
+
9
88
  ## [7.7.2] — 2026-10-05
10
89
 
11
90
  Panels re-render only when something about them changes. Before, focusing one panel or moving a
@@ -522,6 +601,12 @@ Fixes found by a consumer migrating a 30-file app from 6.4.0 with the 7.0.0 migr
522
601
 
523
602
  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.
524
603
 
604
+ > **Why so much broke at once** (note added 2026-10-06). This release renamed most of the public
605
+ > API in one go, with no deprecation period, so that the React, Vue and Angular editions of this
606
+ > library share one vocabulary. That was a one-time cost, and it won't be repeated: from 7.0.0 on,
607
+ > an API is deprecated before it is removed, and removed only in a major version. See
608
+ > [STABILITY.md](STABILITY.md).
609
+
525
610
  ### Breaking
526
611
  - **React 18 or later.** The peer range said 16.8; the library already relied on React 18 APIs.
527
612
  - **`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.
@@ -973,7 +1058,9 @@ All of the above is additive and backward-compatible: every new field is optiona
973
1058
 
974
1059
  ---
975
1060
 
976
- [Unreleased]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.7.2...HEAD
1061
+ [Unreleased]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.7.4...HEAD
1062
+ [7.7.4]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.7.3...v7.7.4
1063
+ [7.7.3]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.7.2...v7.7.3
977
1064
  [7.7.2]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.7.1...v7.7.2
978
1065
  [7.7.1]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.7.0...v7.7.1
979
1066
  [7.7.0]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.6.2...v7.7.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.7.2-blue.svg)](https://www.npmjs.com/package/react-dockable-desktop)
3
+ [![npm version](https://img.shields.io/badge/npm-v7.7.4-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)
@@ -436,7 +436,7 @@ Every release is documented in one place — see the
436
436
  **[CHANGELOG](https://github.com/felipecarrillo100/react-dockable-desktop/blob/main/CHANGELOG.md)**
437
437
  for the full, up-to-date history of additions, fixes, and breaking changes.
438
438
 
439
- Upgrading across a major version? See the [Migration Guide](https://felipecarrillo100.github.io/react-dockable-desktop/guide/migration).
439
+ 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
440
 
441
441
  ---
442
442
 
@@ -462,6 +462,7 @@ Complete guides, API reference, and interactive demo at:
462
462
  | [Panel Overlay](https://felipecarrillo100.github.io/react-dockable-desktop/guide/panel-overlay) | `RddPanelOverlay`, panel toolbars, `RddFloatingWidget`, `useFloatingWidgets` |
463
463
  | [Toast Notifications](https://felipecarrillo100.github.io/react-dockable-desktop/guide/toast) | `toast` singleton, `<RddToasts>`, queue behaviour, theming, `ToastAdapter` |
464
464
  | [Migration Guide](https://felipecarrillo100.github.io/react-dockable-desktop/guide/migration) | Upgrading across major versions |
465
+ | [Stability & Versioning](https://felipecarrillo100.github.io/react-dockable-desktop/guide/stability) | What the public API is, deprecation and support periods |
465
466
  | [API Reference](https://felipecarrillo100.github.io/react-dockable-desktop/api/) | Full type-level reference for all exports |
466
467
 
467
468
  ---
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.