vue-dockable-desktop 1.1.1 → 1.2.0

package/CHANGELOG.md

@@ -11,6 +11,154 @@ correspondence lives, alongside the feature-by-feature map in [docs/PARITY.md](d
 
 ## [Unreleased]
 
+## [1.2.0] — 2026-09-24
+
+**Parity: react-dockable-desktop 6.3.1.**
+
+The remaining items from the user bug report that 1.1.2 left for a minor release: they add
+behaviour, change a default, or extend a public type.
+
+### Added
+
+- **Tabs work from the keyboard.** Each tab group is one stop in the Tab order — its selected
+  tab. ArrowLeft and ArrowRight move to the previous or next tab and show it, wrapping, and
+  mirrored under RTL; Delete closes the focused tab, asking first if it has unsaved changes.
+  The tab strip is a `tablist` and the body a `tabpanel`; a tab's close × is hidden from
+  assistive technology, since Delete and the menu's Close cover it. A focus ring shows for
+  keyboard focus only.
+
+- **The context menu works from the keyboard.** It takes focus when it opens; ArrowDown and
+  ArrowUp move between enabled items, Enter or Space runs one, and Tab or Escape closes it.
+  Closing from the keyboard, or by running an item, hands focus back to whatever had it. A
+  submenu now also opens on click, which helps on touch screens. A custom menu slot manages
+  its own focus.
+
+- **`--vdd-font-family`, one token for the font of all library chrome.** Set it to change the
+  font of the workspace, sidebar, toolbar, modals, side panels, toasts, menus and flyouts in
+  one place, or to `inherit` to use your page's font. See the theming chapter.
+
+- **Two message keys: `notifications` and `closeNotification`.** The toast region's
+  accessible name and a toast's close button were hard-coded English, as was the sidebar
+  drawer's close button (now the existing `close` key). They go through the message table and
+  formatter like every other string, and fall back to English where there is no workspace.
+
+- **`<VddDesktop>` can be set up without a DOM.** Server-rendering it threw
+  `document is not defined` and took the whole page render down. It now renders the chrome and
+  leaves the panels to the client. `<ClientOnly>` remains the supported setup under Nuxt or
+  other SSR, and the getting-started chapter says so.
+
+### Changed
+
+- **The chrome's default font.** The context menu used the system font stack while the rest of
+  the chrome used the workspace's, and everything rendered outside the workspace — the sidebar
+  and toolbar around it, modals, side panels, toasts, menus and flyouts — took the host page's
+  body font. All of it now uses `--vdd-font-family`, which defaults to the workspace's stack.
+  To keep the page's font, set `--vdd-font-family: inherit`.
+
+- **`MessageKey` has two more keys.** A table typed `Record<MessageKey, string>`, as the i18n
+  chapter recommends, fails to compile until it adds `notifications` and `closeNotification`.
+  That is the check doing its job; partial `messages` overrides are unaffected.
+
+## [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.**

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/useLibraryMessage.d.ts

@@ -0,0 +1,10 @@
+import type { MessageKey } from '../core/messages';
+/**
+ * One of the library's own strings, for a component that may render with no workspace.
+ *
+ * Toasts work from anywhere and a sidebar can stand alone, so these cannot `useWorkspace()`,
+ * which throws without one. With a workspace the string goes through its message table and
+ * formatter, exactly as every other library label does; without one it is the English
+ * default. Call the returned function during render, so a locale change is followed. @internal
+ */
+export declare function useLibraryMessage(): (key: MessageKey) => string;

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/messages.d.ts

@@ -107,6 +107,14 @@ export declare const defaultMessages: {
         readonly id: "vdd.search";
         readonly defaultMessage: "Search";
     };
+    readonly notifications: {
+        readonly id: "vdd.notifications";
+        readonly defaultMessage: "Notifications";
+    };
+    readonly closeNotification: {
+        readonly id: "vdd.closeNotification";
+        readonly defaultMessage: "Close notification";
+    };
 };
 /**
  * Every message key. Import it in your own message table to get a compile-time guarantee

package/dist/core/panelDom.d.ts

@@ -13,7 +13,7 @@
  * workspaces on a page shared panel DOM.
  */
 export declare class PanelDomCache {
-    private readonly doc;
+    private readonly ownerDocument?;
     private elements;
     /**
      * Preserved state, **owned per panel and outliving the hidden period**.
@@ -34,7 +34,13 @@ export declare class PanelDomCache {
      */
     private sizes;
     private hidden;
-    constructor(doc?: Document);
+    /**
+     * The document is looked up on first use, not in a parameter default: constructing the cache
+     * then touches nothing, so `<VddDesktop>` can be set up where there is no DOM (server
+     * rendering) as long as no panel element is asked for.
+     */
+    constructor(ownerDocument?: Document | undefined);
+    private get doc();
     /** The off-screen store. Panels live here while minimised, and before their first host. */
     hiddenStore(): HTMLElement;
     /**

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>;