vue-dockable-desktop 1.1.0 → 1.1.2

package/CHANGELOG.md

@@ -11,6 +11,170 @@ correspondence lives, alongside the feature-by-feature map in [docs/PARITY.md](d
 
 ## [Unreleased]
 
+## [1.1.2] — 2026-09-24
+
+**Parity: react-dockable-desktop 6.3.1.**
+
+Fixes from a user bug report. Every item was reproduced before it was fixed, and each fix has a
+regression test that fails against 1.1.1. No public API changes: the export list in
+`api-surface.json` is unchanged.
+
+### Fixed
+
+- **One Escape could close several things.** Modals, drawers, the context menu, the toolbar
+  flyout and the toolbar search all listen for Escape, most of them on `document`, and the
+  answering modal's `stopPropagation()` never stopped the other listeners there. So a drawer
+  opened *after* a modal closed along with it; a context menu, toolbar flyout or toolbar search
+  inside a modal or drawer closed its host too; and with a drawer on each side, one press
+  closed both. Whoever acts on Escape now claims the event, and every other listener checks for
+  a claim first. Transient UI answers before overlays: the menu and flyout listen in the
+  capture phase, and the search claims on its own input. With two drawers open, the one opened
+  last closes first. An application widget inside a modal can keep the modal open by calling
+  `event.preventDefault()` on its own Escape. [ADR 0016](docs/decisions/0016-escape-claiming.md),
+  divergence D17 in [PARITY.md](docs/PARITY.md). Covered by `test/components/escapeRouting.test.ts`.
+
+- **A custom context-menu slot closed before its items could be clicked.** In slot mode the
+  outside-press check had no element for the slot, so the `pointerdown` of any click inside it
+  counted as outside and closed the menu; the `click` then never reached the item. The slot is
+  now wrapped in a `display: contents` element that counts as inside. The docs said dismissal
+  "becomes yours" in slot mode; it does not — Escape and an outside press still close the menu.
+
+- **`usePanel()` did not work inside a modal or side panel.** It looked the panel up in the
+  docked-panel state, which holds no overlays. So `onBeforeClose` registered nothing, and Escape
+  or `close()` closed the overlay regardless; `onSaveState` and `minimize` warned that the panel
+  was "rendered standalone"; `title` returned the instance id, and `dirty` stayed `false` after
+  `setDirty(true)`. The overlay now supplies its title, dirty state and guard registration, and
+  `onSaveState` and `minimize` say accurately why they do nothing there.
+
+- **A toast adapter's `show` was never called.** A new toast only went into the built-in queue;
+  only a repeat of its id reached the adapter, as `update`. The queued records were never
+  removed either, so they piled up and all appeared at once if the adapter was later unset.
+  In adapter mode nothing is queued now: a new id goes to `show` — with `type` and the
+  container's `defaultDuration` and `defaultClosable` filled in — a repeated id to `update`,
+  and a dismissed id used again is a new `show`. Toasts raised before the adapter mounts are
+  handed to it. A toast's `onClose` is not called in adapter mode, and the docs now say so.
+
+- **`loadLayout` accepted a partial layout and cleared the workspace.** Valid JSON with a
+  `gridRoot` but without `floating`, `minimized` or `panels` parsed to an *empty* workspace,
+  which `loadLayout` applied and reported as success — every open panel closed, and `true`
+  returned. It now returns `false` with a warning and leaves the layout unchanged.
+
+- **Right-to-left gestures went the wrong way.** A pointer delta is physical, while the sizes,
+  sides and tab indexes it changes are logical, and a flex row reverses under RTL:
+  - a horizontal split divider moved away from the pointer;
+  - a sidebar resizer shrank the drawer when dragged away from its edge;
+  - a toolbar flyout was placed by the workspace's direction, though the strip sits outside the
+    workspace and follows the page — so an RTL workspace in an LTR page opened a left strip's
+    flyout off-screen, and the viewport clamp pulled it back over the strip;
+  - a tab dropped on another tab's left half was inserted on its right, and vice versa.
+
+  Each gesture now reads its own element's computed direction when it starts. The manual's RTL
+  section says that `<VddSidebar>` and `<VddToolbar>` follow the page's `dir`, not the
+  workspace's.
+
+- **`.vdd-fill-viewport` did nothing on `<VddDesktop>` itself.** There the class shares an
+  element with `.vdd-workspace`, whose `height: 100%` has equal specificity and comes later. A
+  compound selector now outranks it. The zero-height warning, which recommends the class, says
+  where it can go.
+
+- **A quick click on a taskbar icon could land on its preview.** The preview rose into place
+  from below — starting at 90% of its lift, over the icon — so for its first frames a click or
+  right-click meant for the icon hit the preview; and its hover bridge reached 4px past the gap
+  even at rest. It now drifts down into place from just above, so neither the preview nor its
+  bridge ever covers the icon, and the bridge spans exactly the 8px gap. Measured frame by
+  frame in Chrome: a start below the resting place, even by 6px, still put the bridge over the
+  top of the icon.
+
+- **A collapsed toolbar left a 1px line and kept its buttons in the Tab order.** Collapsing only
+  set the strip's size to zero. It now also removes the edge border and makes the strip `inert`.
+
+- **Invalid ARIA.** Toolbar flyout tools were `role="menuitem"` with `aria-pressed`; they are
+  now `menuitemradio` with `aria-checked`. Checkbox context-menu items carried `aria-checked` on
+  a plain `menuitem`; they are now `menuitemcheckbox`. The toast container's `aria-label` sat on
+  a `<div>` with no role, where it is ignored; it now has `role="region"`.
+
+- **An event map declared as an `interface` failed to compile.** The manual shows
+  `interface MyEvents { … }`, but the type parameter was constrained to
+  `Record<string, unknown>`, which an interface does not satisfy (TS2344). The constraint on
+  `createWorkspace`, `Workspace`, `useWorkspace` and `EventBus` is now `object`, so interfaces
+  and type aliases both work. Payloads are still checked against the map.
+
+### Documentation
+
+- Removed the `#panel-actions` slot on `<VddDesktop>`, which was documented but never existed
+  (manual and PARITY.md); the manual now says where a panel's own actions belong.
+- `updateSplitSizes`: the root branch's path is `[]`; `[0]` is its first child.
+- `<VddFloatingWidget>` takes `widget-id`, not `id`, in the migration guide.
+- A close guard does not replace the unsaved-changes question: it runs first, and a dirty panel
+  is still asked about.
+- Only `useSidebar()` works from a panel in the workspace; `useSidebarTab()` needs a drawer tab.
+- Filled in the empty table of theme tokens that have no base value, and corrected the prose
+  around it: every rule that reads them has a fallback, and no built-in skin sets them.
+
+## [1.1.1] — 2026-09-19
+
+**Parity: react-dockable-desktop 6.3.1.**
+
+### Fixed
+
+- **Dragging the only docked panel onto its own group made it disappear.** With one panel in
+  the workspace, dropping it on its own drop cross — any side, the centre, or its own tab
+  strip — left the panel `docked` but in **no group**: no tab, nothing rendered, and still
+  listed as open. Re-opening it did nothing, because an already-open panel is only focused;
+  the only way back was to minimise and restore it, which returned it as a floating window.
+  Dropping it on a workspace edge left an empty group holding half the width instead.
+
+  The cause: the dock actions detach the panel before resolving the target, and detaching the
+  only panel of a group **deletes that group** — so the drop destroyed the very target it
+  named, and `splitLeafInTree` then had nothing to find. Dropping a lone panel onto its own
+  group is now a no-op, since the result would be the layout it already has. Guarded in the
+  store rather than in the drag layer, so `dockPanelToGroup`, `movePanelOrder` and
+  `dockPanelToWorkspaceEdge` are safe for any caller, not just the mouse. The same bug, in a
+  different shape, was [reported against react-dockable-desktop](https://github.com/felipecarrillo100/react-dockable-desktop)
+  and fixed there in 6.3.1 — there it duplicated the panel into two groups instead.
+
+- **A dock into a group that no longer exists no longer loses the panel.** Emptying a group
+  removes it, so an id held across a layout change can name one that is gone; placing into it
+  left the panel in no group. `dockPanelToGroup` and `movePanelOrder` now ignore such a call
+  with a development warning.
+
+- **Layouts already saved in the broken state are repaired when read.** `saveLayout()` wrote
+  the corrupted tree out, so the fault came back on every reload and a stored layout stayed
+  broken. Reading one now drops a panel listed in more than one group from all but the first,
+  prunes a group emptied by that unless it set `keepOnEmpty`, collapses a branch left with one
+  child, and puts a panel the layout calls docked but that no group lists back into the first
+  group, naming each repair in a development warning. Only what is *read* changes — the saved
+  format is untouched, so every rdd fixture still round-trips byte-identically.
+
+- **`openPanel` recovers a panel that is in no group** instead of only focusing it — a safety
+  net, now that nothing should produce that state.
+
+- **An emptied root group keeps its own identity.** Removing the last panel replaced the root
+  leaf with a fresh `group-default`, so a leaf the application had named, or had marked
+  `keepOnEmpty` or `canClose: false`, silently lost all three.
+
+Covered by `test/store/selfDrop.test.ts` (20), the repair and the guard as pure functions in
+`test/core/layoutTree.test.ts`, and three compatibility tests for layouts written by 1.1.0.
+New M6 rules keep the guard in the store rather than in the drag layer, and new M4 rules keep
+the repair on the shared read path.
+
+### Fixed — the gate harness itself
+
+- **`npm run gate:selftest` was proving almost nothing.** It ran each gate as `node ${gate}`
+  while 77 of its 89 checks passed a gate that already began with `node`, so the command
+  executed was `node node scripts/gates/mN.mjs` — which fails whatever the mutation did, and a
+  failing gate is exactly what the harness reads as "this rule caught its violation". Those
+  rules were reported as proven without their gate ever running. The command is now used as
+  given, and a mutation that changes no bytes is reported as a miss in its own right, since a
+  stale anchor is the other way a check quietly stops testing anything.
+
+  With the harness honest, four checks were failing: two pinned `version = '1.0.0'`, stale
+  since 1.0.1, and now match any version; and two M14 capability checks were satisfied by
+  *prose* — the capability scan read whole files, so a doc comment or a `<code>onBeforeClose()`
+  in a paragraph counted as a demonstration. Capabilities that are called are now looked for in
+  script blocks with comments stripped, and the two that are bound in markup are matched on a
+  `<Vdd…>` tag. All 89 rules now genuinely fail when their rule is broken.
+
 ## [1.1.0] — 2026-09-18
 
 **Parity: react-dockable-desktop 6.3.0.**

package/dist/components/VddContextMenu.vue.d.ts

@@ -12,8 +12,9 @@ type __VLS_Slots = {
      * and it needs no provider, no ref handshake and no adapter object.
      *
      * `items` is the pending menu, `x`/`y` the requested position, and `close` dismisses it.
-     * Positioning and dismissal are then yours: the built-in clamping, Escape handling and
-     * outside-click handling belong to the built-in markup this replaces.
+     * Positioning and keyboard navigation are then yours: the built-in viewport clamping
+     * belongs to the markup this replaces. Dismissal is not — Escape and a press outside the
+     * slot still close the menu, and a press inside it does not.
      */
     default?: (props: {
         items: ContextMenuItem[];

package/dist/composables/useOverlayHost.d.ts

@@ -12,7 +12,8 @@ import type { OverlayInstance } from '../core/overlays';
  * **Escape routing** lives here too, and is the reason it can be stated once: Escape belongs
  * to the topmost modal, and reaches a drawer only when no modal is open. rdd expressed the
  * same rule twice, in two different shapes (`modals.length === 0` in one,
- * `isTopmost` in the other).
+ * `isTopmost` in the other). With a drawer on each side and no modal, the one opened last
+ * answers. Whoever answers claims the event (`../core/escape`), so one Escape closes one thing.
  */
 export declare function useOverlayHost(instance: MaybeRefOrGetter<OverlayInstance>): {
     /** The instance's title, resolved through the formatter, with a trailing `*` when dirty. */

package/dist/composables/usePanel.d.ts

@@ -15,6 +15,16 @@ export interface PanelContext {
         width: number;
         height: number;
     } | null>;
+    /** Live title and dirty state, for a container whose panel is not in `ws.state.panels`. */
+    title?: Ref<Label>;
+    dirty?: Ref<boolean>;
+    /** Register a close guard with the container; returns its disposer. */
+    onBeforeClose?: (guard: () => boolean | Promise<boolean>) => () => void;
+    /**
+     * Set by a modal or side panel: it is not part of the layout, so it has nothing to save
+     * and nowhere to minimise to. Lets `usePanel()` say so rather than call it standalone.
+     */
+    overlay?: boolean;
 }
 export declare const PANEL_KEY: InjectionKey<PanelContext>;
 /** @internal — used by containers to tell their content which panel it is. */

package/dist/composables/useWorkspace.d.ts

@@ -15,4 +15,4 @@ import type { Workspace } from '../core/workspace';
  * `subscribe()` is wrapped so a subscription made during `setup` is disposed with the
  * component. Outside a scope it behaves exactly like `workspace.subscribe`.
  */
-export declare function useWorkspace<TEvents extends Record<string, unknown> = Record<string, unknown>>(): Workspace<TEvents>;
+export declare function useWorkspace<TEvents extends object = Record<string, unknown>>(): Workspace<TEvents>;

package/dist/core/dragResize.d.ts

@@ -35,6 +35,25 @@ export interface PointerDragConfig<TStart> {
  * cleans up automatically on release or cancel.
  */
 export declare function startPointerDrag<TStart>(config: PointerDragConfig<TStart>): void;
+/**
+ * Whether `el` lays out right to left, as the browser computed it.
+ *
+ * A pointer delta is physical, but a flex row reverses under RTL, so a gesture that changes a
+ * logical size or index has to know which way its own element runs. The element's computed
+ * direction is the only source that is right everywhere: the sidebar and toolbar sit
+ * *outside* the workspace, and take their direction from the host page, not from the
+ * workspace's `dir`. Read it once, when the gesture starts.
+ */
+export declare function isRtlElement(el: Element | null | undefined): boolean;
+/**
+ * Which logical side of a tab the pointer is over: `'left'` means before it in tab order,
+ * `'right'` after it — the meaning the insertion index and the RTL indicator CSS both use.
+ * Under RTL the physical left half is the logical end.
+ */
+export declare function tabSide(clientX: number, rect: {
+    left: number;
+    width: number;
+}, rtl: boolean): 'left' | 'right';
 export type ResizeDir = 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w' | 'nw';
 export interface ResizeRect {
     x: number;

package/dist/core/escape.d.ts

@@ -0,0 +1,4 @@
+/** Mark an Escape as answered, so no other listener in the library acts on it. */
+export declare function claimEscape(event: Event): void;
+/** Whether a listener in the library, or the application via `preventDefault()`, already answered it. */
+export declare function isEscapeClaimed(event: Event): boolean;

package/dist/core/eventBus.d.ts

@@ -50,7 +50,7 @@ export interface BuiltInEvents {
         }[];
     };
 }
-export declare class EventBus<TEvents extends Record<string, unknown> = Record<string, unknown>> {
+export declare class EventBus<TEvents extends object = Record<string, unknown>> {
     private listeners;
     subscribe<K extends keyof (TEvents & BuiltInEvents) & string>(event: K, callback: (data: (TEvents & BuiltInEvents)[K]) => void): () => void;
     publish<K extends keyof (TEvents & BuiltInEvents) & string>(event: K, data: (TEvents & BuiltInEvents)[K]): void;

package/dist/core/layoutTree.d.ts

@@ -56,6 +56,36 @@ export declare function findFirstLeafId(node: LayoutNode): string | null;
 export declare function findLeafForPanel(node: LayoutNode, id: string): string | null;
 /** A leaf by id, or `null`. */
 export declare function findLeaf(node: LayoutNode | null, leafId: string): LayoutLeafNode | null;
+/**
+ * Is `panelId` the only panel in `leafId`?
+ *
+ * The question every dock action has to ask *before* it detaches anything. Detaching a panel
+ * deletes its leaf once that leaf is empty, so a drop onto the dragged panel's own leaf
+ * destroys the very target it names, and the placement that follows has nowhere to go.
+ * Dropping a lone panel onto itself is a no-op by definition: the result is the layout it
+ * already has.
+ */
+export declare function isLoneOccupant(node: LayoutNode, leafId: string, panelId: string): boolean;
+/**
+ * Heal a tree that lists a panel twice, or lists none of a docked panel.
+ *
+ * Both are states this library once produced and then *saved*: a lone docked panel dropped
+ * on its own group left rdd with the panel in two leaves and vdd with it in none, and
+ * `saveLayout()` wrote the result out, so the fault returned on every reload. Repairing on
+ * read means a layout stored by an affected version loads clean with nothing asked of the
+ * application. It changes only what is read; `saveLayout()`'s output is untouched, which is
+ * what keeps the format compatible (docs/decisions/0009-layout-json-compatibility.md).
+ *
+ * `repairs` is empty and the input object is returned unchanged when there is nothing wrong,
+ * so a healthy layout costs one walk and no allocation.
+ */
+export declare function repairLayoutTree(gridRoot: LayoutNode, panels: Record<string, {
+    id: string;
+    state: PanelInfo['state'];
+}>): {
+    gridRoot: LayoutNode;
+    repairs: string[];
+};
 /** Whether a leaf exists in the tree. */
 export declare function leafExists(node: LayoutNode, leafId: string): boolean;
 /** Update the sizes of the branch at `path` (a list of child indices from the root). */

package/dist/core/toast.d.ts

@@ -58,6 +58,11 @@ export interface ToastAdapter {
     dismiss(id?: string): void;
     component: Component | null;
 }
+/** What `<VddToasts>` would fill in for an option the caller left out. */
+export interface ToastDefaults {
+    duration: number;
+    closable: boolean;
+}
 /** The live queue. Exported for `<VddToasts>` and for tests; applications use `toast`. */
 export declare const toastQueue: {
     items: {
@@ -438,6 +443,10 @@ export declare const toastQueue: {
             __name?: string | undefined;
         } | null;
     } | null;
+    defaults: {
+        duration: number;
+        closable: boolean;
+    };
 };
 /** Begin the exit transition. `<VddToasts>` removes the record when it finishes. */
 export declare function startExit(id: string): void;
@@ -472,3 +481,11 @@ export interface ToastFunction {
 export declare const toast: ToastFunction;
 /** Empty the queue with no animation. For tests and for a full application teardown. */
 export declare function resetToasts(): void;
+/**
+ * Hand `toast.*` to an adapter, or take it back with `null`. Used by `<VddToasts>`.
+ *
+ * Toasts raised before an adapter arrives are waiting in `items`; they are handed to it, so a
+ * toast raised during start-up is not lost. The adapter's ids are forgotten when it changes —
+ * a new adapter has shown none of them.
+ */
+export declare function setToastAdapter(adapter: ToastAdapter | null, defaults: ToastDefaults): void;

package/dist/core/workspace.d.ts

@@ -95,7 +95,7 @@ export interface WorkspaceState {
     edgeSplitRatio: number;
 }
 /** A workspace instance: reactive state, actions, registry, and a Vue plugin. */
-export interface Workspace<TEvents extends Record<string, unknown> = Record<string, unknown>> {
+export interface Workspace<TEvents extends object = Record<string, unknown>> {
     /** The whole state, read-only. Reactive — use it in templates and `computed`. */
     readonly state: Readonly<WorkspaceState>;
     /** The panel catalogue. */
@@ -219,4 +219,4 @@ export declare const WORKSPACE_KEY: InjectionKey<Workspace<never>>;
  * The returned object is both the imperative API and a Vue plugin, matching the
  * `createPinia()` / `createRouter()` shape a Vue developer already knows.
  */
-export declare function createWorkspace<TEvents extends Record<string, unknown> = Record<string, unknown>>(config?: WorkspaceConfig): Workspace<TEvents>;
+export declare function createWorkspace<TEvents extends object = Record<string, unknown>>(config?: WorkspaceConfig): Workspace<TEvents>;