vue-dockable-desktop 1.8.2 → 1.10.0

package/CHANGELOG.md

@@ -11,6 +11,97 @@ correspondence lives, alongside the feature-by-feature map in [docs/PARITY.md](d
 
 ## [Unreleased]
 
+## [1.10.0] — 2026-10-06
+
+**Parity: react-dockable-desktop 7.9.0.** Control over where users can move panels: per-kind rules and
+an app-wide veto, all opt-in. Without them nothing changes, and the app's own calls are never
+restricted. Same names as rdd 7.9.0.
+
+### Added
+
+- **`canFloat` and `canDock` per kind**, next to `canDrag`, `canMinimize` and `canClose`.
+  `canFloat: false` keeps a panel in the grid: a tab drag can't end in a floating window, and
+  "Float Window" and the taskbar's "Maximize" are hidden. `canDock: false` keeps a panel floating:
+  dragging it offers no group, tab or edge targets.
+- **`canDrop`, an app-wide veto.** `createWorkspace({ canDrop: ({ panelId, component, to }) => boolean })`
+  is asked for every place a dragged panel could go, and for the "Float" and "Maximize" menu items;
+  `to` is a `PanelDropTarget` (a group, an edge, or a float). A forbidden target isn't offered, and
+  it's asked again at release. Positions and corners are the ones the move applies, mirrored under
+  RTL. If it throws, the move is allowed and the error is logged. New types: `PanelDrop`,
+  `PanelDropTarget`.
+- Both apply only to what the user does; the app's own calls always work.
+
+### Fixed
+
+- **A drag built on `startPointerDrag` could outlive its element.** It ended on pointerup,
+  pointercancel and window blur, but not when the capturing element was removed mid-drag (an
+  overlay widget closed during its own drag), which left its listeners attached and its classes on
+  the page. It now also ends on a lost pointer capture, listened for on the document, where browsers
+  fire it; `onCancel` runs if given.
+
+### Docs
+
+- Layout (Chapter 4): **Controlling where users can move panels**. Panels (Chapter 3) and the API
+  reference: the new options. `PARITY.md`: the rdd 7.9.0 trace.
+
+### Tests
+
+- `test/components/releaseB.test.ts` (12 tests): `canFloat` (no float on nothing, no corners, no
+  "Float Window" or "Maximize" from a group, the app's `floatPanel` still works), `canDock` (no group
+  or edge targets, only corners), `canDrop` (its argument, vetoed zones and edges not offered, RTL
+  positions, tab insertion into a vetoed group, rules changed mid-drag for zones and tabs, a throwing
+  `canDrop`, no rules meaning every target), and `startPointerDrag` ending on a lost capture. Each
+  rule was seen failing with it broken. `api-surface.json` gains the two types.
+
+## [1.9.0] — 2026-10-06
+
+**Parity: react-dockable-desktop 7.8.0.** More control over how the desktop looks and where panels
+open, all opt-in: without the new options, nothing changes. Same names as rdd 7.8.0, in Vue's idiom.
+
+### Added
+
+- **Your own empty-workspace view.** `<VddDesktop>` takes a `#empty-workspace` slot, shown while no
+  panel is docked in place of the built-in message: a welcome screen, a logo, "Open a file"
+  buttons. Floating windows still show over it, and a window can still be dropped onto it to dock.
+  Empty groups inside a split keep the built-in message.
+- **Open a panel beside another.** `openPanel(id, component, { dockTo: { panel, position, size } })`
+  docks a new panel as a tab in that panel's group (`position: 'center'`) or in a new group split
+  off on one side, taking `size` (0.1–0.9) of the split. It wins over `initialTarget`. If the
+  target isn't docked, the panel is placed as usual and a warning says why.
+- **State attributes for your CSS.** Tabs carry `data-vdd-selected`, `data-vdd-focused` and
+  `data-vdd-dirty`; floating windows carry `data-vdd-focused` and `data-vdd-maximized`. Each is
+  present only while it is true. The existing classes are unchanged.
+- **Per-kind classes.** `className` and `tabClassName` in a kind's `defaultOptions` add your class
+  to every panel of that kind (on its content element, which moves with it) and to its tab.
+- **`keepAlive: false`**, per kind: the component unmounts while the panel is an unselected tab or
+  minimised, and mounts afresh when shown. Its own state is lost each time, and in such a panel
+  `onUnmounted` means hidden, not closed; a guard it registered with `onBeforeClose` is inactive
+  while it is unmounted, though its dirty flag still applies. The default is unchanged: panels
+  stay mounted. Recorded as [ADR 0021](docs/decisions/0021-opt-in-unmount-while-hidden.md), which
+  amends 0002 for kinds that opt in.
+
+### Docs
+
+- Theming (Chapter 10): **Your own empty-workspace view**, **Styling by state and by panel kind**,
+  and **Using it with Vuetify, PrimeVue, Bootstrap or Tailwind** (dark mode, the library's
+  z-index layers, why a framework popup opened inside one of the library's modals appears behind
+  it and the fixes, overriding styles). Layout (Chapter 4): **Opening beside another panel**.
+  Panels (Chapter 3): the new registration options and **Freeing a hidden panel**. Concepts
+  (Chapter 2) notes the `keepAlive: false` exception beside the zero-unmount guarantee.
+- `PARITY.md`: the rdd 7.8.0 trace.
+
+### Tests
+
+- `test/components/releaseA.test.ts` (15 tests): the empty-workspace slot (shown and gone as panels
+  dock and close; empty groups inside a split keep the built-in message), the state attributes on
+  tabs and windows, `dockTo` (sides, centre, size clamping, winning over `initialTarget`, the
+  fallback and its warning, no effect on an open panel), the per-kind classes (also after
+  floating), and `keepAlive: false` (unmount and fresh remount, the default unchanged, no leak
+  over 50 hide/show cycles). Each was seen failing with its feature broken.
+- M13's browser tour gains a step that shows the playground's `#empty-workspace` view, so the new
+  `.vdd-empty-workspace` rule is checked against a real render (the gate first failed on it as a
+  dead rule, which is what it is for).
+
 ## [1.8.2] — 2026-10-06
 
 **Parity: react-dockable-desktop 7.7.3** (code health). Neither of rdd's last two releases needs a

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

@@ -15,7 +15,11 @@ type __VLS_Props = {
     /** Fallback icon for panels that register none. */
     defaultPanelIcon?: unknown;
 };
-declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+declare var __VLS_13: {};
+type __VLS_Slots = {} & {
+    'empty-workspace'?: (props: typeof __VLS_13) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     taskbarContextMenu: (panelId: string, event: MouseEvent | PointerEvent) => any;
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
     onTaskbarContextMenu?: ((panelId: string, event: MouseEvent | PointerEvent) => any) | undefined;
@@ -25,5 +29,11 @@ declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {
     taskbar: TaskbarVisibility;
     defaultPanelIcon: undefined;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
 declare const _default: typeof __VLS_export;
 export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

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

@@ -2,6 +2,16 @@ import type { LayoutLeafNode } from '../types';
 type __VLS_Props = {
     leaf: LayoutLeafNode;
 };
-declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare var __VLS_16: {};
+type __VLS_Slots = {} & {
+    'empty-workspace'?: (props: typeof __VLS_16) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
 declare const _default: typeof __VLS_export;
 export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

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

@@ -3,6 +3,16 @@ type __VLS_Props = {
     node: LayoutNode;
     path: number[];
 };
-declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare var __VLS_9: {};
+type __VLS_Slots = {} & {
+    'empty-workspace'?: (props: typeof __VLS_9) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
 declare const _default: typeof __VLS_export;
 export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/core/dockRules.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Docking rules (1.10.0): what the *user* may do with a panel. The kind's own `canFloat` /
+ * `canDock` first, then the workspace's `canDrop`. Never consulted by the app's own calls.
+ */
+import type { PanelDropTarget } from '../types';
+import type { Workspace } from './workspace';
+type RuleHost = Pick<Workspace<never>, 'state' | 'registry' | 'config'>;
+export declare function isDropAllowed(ws: RuleHost, panelId: string, to: PanelDropTarget): boolean;
+export {};

package/dist/core/panelMenu.d.ts

@@ -8,6 +8,7 @@
 import type { ContextMenuItem } from './contextMenu';
 import type { PanelDefaultOptions } from './registry';
 import type { Label, MessageDescriptor } from '../types';
+import type { Workspace } from './workspace';
 /**
  * Just enough of the workspace to build a menu, so this module does not depend on the store.
  *
@@ -19,6 +20,10 @@ interface MenuHost {
     format: (label: Label | undefined) => string;
     messages: Record<string, MessageDescriptor>;
     panelMenuItems: (id: string) => ContextMenuItem[];
+    /** For the docking rules (1.10.0): floating is a move they decide. */
+    state: Workspace<never>['state'];
+    registry: Workspace<never>['registry'];
+    config: Workspace<never>['config'];
 }
 export interface PanelMenuActions {
     float: () => void;

package/dist/core/registry.d.ts

@@ -23,6 +23,19 @@ export interface PanelDefaultOptions {
     canMinimize?: boolean;
     /** Allow dragging the tab, which is also what allows floating by drag. @default true */
     canDrag?: boolean;
+    /**
+     * `false`: the user can't make this panel floating. A tab drag can't end in a floating window
+     * (dropped on nothing or on a corner, it stays where it was), and "Float Window" and the taskbar's
+     * "Maximize" are hidden. A window the app floated itself can still be moved. The app's own
+     * `floatPanel` always works. @default true (1.10.0)
+     */
+    canFloat?: boolean;
+    /**
+     * `false`: the user can't dock this panel. Dragging it offers no group, tab or edge targets
+     * (corners still pin a floating window), so it stays floating. The app's own docking calls always
+     * work; give the kind `initialTarget: 'floating'` so it opens floating. @default true (1.10.0)
+     */
+    canDock?: boolean;
     /** Show a letter tile instead of a live thumbnail in the taskbar hover preview. @default false */
     disableLivePreview?: boolean;
     /**
@@ -32,6 +45,22 @@ export interface PanelDefaultOptions {
      * @see docs/decisions/0014-preserve-scroll-and-focus.md
      */
     preserveScroll?: boolean;
+    /**
+     * Class added to each panel of this kind, on its own content element (`.vdd-panel-content`),
+     * which moves with the panel between groups, windows and the taskbar preview. (1.9.0)
+     */
+    className?: string;
+    /** Class added to the tab of each panel of this kind. (1.9.0) */
+    tabClassName?: string;
+    /**
+     * `false` unmounts the panel's component while it is hidden (an unselected tab, or minimised)
+     * and mounts it afresh when shown, to free what a heavy, rarely shown panel holds. Its own
+     * state is lost each time, and a guard it registered with `onBeforeClose` is not active while
+     * it is unmounted (its dirty flag still is). Its tab, title and lifecycle continue, and the
+     * taskbar shows a letter tile instead of a live preview. @default true
+     * @see docs/decisions/0021-opt-in-unmount-while-hidden.md
+     */
+    keepAlive?: boolean;
 }
 /** A registered panel kind. */
 export interface PanelRegistryEntry {

package/dist/core/workspace.d.ts

@@ -1,5 +1,5 @@
 import type { App, Component, ComputedRef, InjectionKey } from 'vue';
-import type { DirtyStateOptions, DropPosition, FloatAnchor, FloatingWindow, Label, LayoutNode, MessageDescriptor, MessageFormatter, PanelInfo, SplitDirection } from '../types';
+import type { DirtyStateOptions, DropPosition, FloatAnchor, PanelDrop, FloatingWindow, Label, LayoutNode, MessageDescriptor, MessageFormatter, PanelInfo, SplitDirection } from '../types';
 import { PanelRegistry } from './registry';
 import type { PanelDefaultOptions } from './registry';
 import type { ContextMenuItem, ContextMenuRequest, ShowContextMenuOptions } from './contextMenu';
@@ -43,6 +43,14 @@ export interface WorkspaceConfig {
      * rendered elements, which is the part that can actually break.
      */
     classes?: HostClasses;
+    /**
+     * Veto where users can move panels (1.10.0). Called for each place a dragged panel could go, and
+     * for the built-in "Float" and "Maximize" menu items: return `false` and that target isn't offered
+     * and the move doesn't happen. It runs after the kind's own `canFloat` / `canDock`, and only for
+     * what the user does: the app's own calls always work. Keep it fast and pure; it runs while the
+     * pointer moves.
+     */
+    canDrop?: (drop: PanelDrop) => boolean;
 }
 /** Consumer classes added to the library's chrome. Every field is optional. */
 export interface HostClasses {
@@ -74,6 +82,18 @@ export interface OpenPanelOptions<P extends object = Record<string, unknown>> {
     props?: P;
     /** If another open panel of the same `component` has this key, focus that one instead. */
     dedupeKey?: string;
+    /**
+     * Dock the new panel beside an open, docked panel: in that panel's group (`position: 'center'`,
+     * as a tab) or in a new group split off on one side of it. `size` is the new group's share of
+     * that split, from 0.1 to 0.9 (the workspace's split ratio when omitted). Wins over
+     * `initialTarget`. If `panel` is not docked (not open, floating or minimised), the new panel is
+     * placed as usual and a warning says why. Applies only to a newly opened panel. (1.9.0)
+     */
+    dockTo?: {
+        panel: string;
+        position: DropPosition;
+        size?: number;
+    };
 }
 /** The live workspace state. */
 export interface WorkspaceState {