vue-dockable-desktop 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -11,6 +11,152 @@ correspondence lives, alongside the feature-by-feature map in [docs/PARITY.md](d
 
 ## [Unreleased]
 
+## [1.1.0] — 2026-09-18
+
+**Parity: react-dockable-desktop 6.3.0.**
+
+### Fixed
+
+- **`<VddDesktop :skin>` did nothing at all.** The stylesheet keyed its 104 skin selectors on
+  `data-workspace-skin` while the component emitted `data-vdd-skin`, so no skin rule had ever
+  matched in any published version: all seven skins painted identically to the default. The
+  stylesheet now uses the library's own `data-vdd-skin`, which is the name the component, its
+  test and [ADR 0008](docs/decisions/0008-css-prefix.md) already agreed on.
+
+  A consumer who wrote a custom skin against `[data-workspace-skin="…"]`, as the manual
+  previously showed, must rename it to `[data-vdd-skin="…"]`. Nothing can break in practice:
+  skins have never applied, so no such CSS was having any effect.
+
+- **Skins would have been unusable in light mode**, which the rename alone would have shipped. A
+  skin's token block matches the workspace element as well as the root, and the colour scheme was
+  only on the root — so a skin's *dark* tokens were re-declared closer to the content than the
+  root's light ones and shadowed them: dark panels with dark text. `<VddDesktop>` now mirrors
+  `data-color-scheme` onto the workspace element beside the skin, which is how rdd has always done
+  it. Measured across seven skins × two schemes on four surfaces; every surface now flips.
+
+- **The sidebar, its drawer and the workspace toolbar were unstyled in dark mode.** Twenty-nine
+  tokens — the whole `--vdd-sidebar-*` family, the rail's icon colours and the workspace toolbar's
+  button states — had their dark values only inside `[data-color-scheme="dark"]`, and that selector
+  never matches: dark is signalled by *removing* the attribute, as `useColorScheme()` documents. So
+  they were undefined exactly when they were needed, and fifteen of them are read with no `var()`
+  fallback, which drops the whole declaration instead of defaulting it. The strips had no
+  background, the drawer inherited black text, and **the selected rail icon had no colour at all**,
+  which is why it appeared not to render.
+
+  Dark is the base look, so those values now live on `:root` and the dark block is gone —
+  `[data-color-scheme="light"]` overrides them, which is all a scheme block should do. An
+  application that sets `data-color-scheme="dark"` explicitly sees no change. Reported from the
+  demo; it affects rdd too, whose own demo happens to set the attribute for both schemes and so
+  never shows it.
+
+- **The sidebar rail did not fill its own column.** `.vdd-sidebar-strip-outer` is full height,
+  but it is a block wrapper — added in this port to own the width-collapse transition — and a
+  block does not stretch its child the way rdd's flex row did. So the strip inside it shrank to
+  its buttons, 216px of a 915px column, and its background covered only the icons while the rest
+  showed the host page through. It has `height: 100%` now.
+
+- **A rail holding one tab collapsed that tab to its icon.** An active rail button takes
+  `width: var(--vdd-tab-btn-active-width, 100%)`, and that percentage resolves against the
+  shrink-to-fit tabs list; with a single tab there is no sibling to hold the list open, so button
+  and list both shrank to 26px against a normal 44px, putting the accent border 15px inboard of
+  the rail's edge. `.vdd-sidebar-tabs-list` now carries the same `min-width: 44px` floor that
+  `.vdd-sidebar-header-area` and `.vdd-sidebar-footer-area` already had for exactly this reason.
+  A rail with several tabs hid it, because the inactive buttons' own 44px kept the list open.
+
+- **Text in a side panel was black on a dark background.** `.vdd-side-panel` set a background
+  and no foreground, so content teleported into a drawer inherited the host page's text colour —
+  the user agent's black. Measured at **1.18:1** in the demo's own Panel manager, against the
+  16.31:1 of the library's title beside it. `.vdd-modal-window`, `.vdd-workspace` and
+  `.vdd-sidebar-content-drawer` all set a colour; the drawer was simply missed. rdd has the same
+  omission, hidden in its demo by Bootstrap's page-wide theme, which this demo deliberately does
+  not import. An application that wants its own colour still sets it on its content or through
+  `createWorkspace({ classes: { sidePanelBody } })`.
+
+- **The theming chapter documented three things that were not true**: the skin selector
+  (`data-workspace-skin`), the claim that *"the workspace publishes its scheme as
+  `data-color-scheme`"* — the library only ever reads it; your application sets it — and a
+  `createWorkspace({ windowClass, modalClass, … })` config shape that has never existed (it is
+  `classes: { window, modal, … }`).
+
+### Added
+
+- **A token reference**: all **119** tokens the library declares on `:root`, in sixteen groups,
+  with defaults and what each paints ([ch. 10](docs/manual/10-theming.md#token-reference)). A gate
+  checks it against the stylesheet in both directions, so a new token needs a row and a row cannot
+  outlive its token.
+
+- **`:root` is now a complete inventory.** Six measurements and off-by-default effects that
+  existed only as `var()` fallbacks are declared at exactly those values, so nothing renders
+  differently — `--vdd-tab-accent-bar-width`, `--vdd-tab-btn-active-glow/-radius/-width`,
+  `--vdd-toolbar-accent-bar-width`, `--vdd-toolbar-btn-active-glow`. Together with the
+  twenty-nine folded out of the dark block, everything a skin may override is declared and
+  documented in one place.
+
+- **Guidance for defining your own skin**, both of it learned by measurement: leave the selector
+  unqualified (`[data-vdd-skin="mono"]`, not `html[…]`, which cannot match the workspace element
+  and loses there), and import your stylesheet after the library's. The demo ships `mono` as a
+  worked example in both schemes, and the browser gate measures it beside the seven built-ins.
+
+### Changed
+
+- The M14 browser gate's skin step used to cycle the seven skins and assert nothing — which is how
+  this shipped. It now measures each skin in both schemes and fails if a surface does not change
+  between them or if a skin paints identically to the default. Two new source rules join it: every
+  `[data-*]` selector in the stylesheet must name an attribute a component emits (the rule that
+  would have caught this on day one), and the token reference must match the stylesheet. A third
+  rejects a token whose only declaration sits inside a colour-scheme block — the shape that left
+  the sidebar unstyled. The browser gate also measures the chrome *outside* the workspace now: the
+  first matrix sampled only inside it, and passed while the sidebar was unpainted. All are proven
+  non-vacuous by `gate:selftest`, now 87 rules.
+
+## [1.0.1] — 2026-09-17
+
+**Parity: react-dockable-desktop 6.3.0.**
+
+### Fixed
+
+- **A widget opened through `useFloatingWidgets()` discarded every placement gesture.** Dropping
+  a managed widget on another corner returned it to the corner `open()` named, and a stretched
+  one lost its stretch as soon as any other widget opened or closed. Template-declared widgets
+  and plain resizes were unaffected. Reported by a user.
+
+  `<VddPanelOverlay>` bound `placement` — a `defineModel` — as a fresh `{ anchor, stretch }`
+  literal with no `@update:placement`, and Vue re-syncs a model from its prop whenever the
+  prop's *identity* changes. Every render of the overlay therefore reset the widget, and the
+  overlay re-renders on exactly the wrong events: a drop clears `draggingId` in the same
+  function that applies the placement, and opening a widget bumps `managedVersion`.
+
+  The overlay now keeps a placement record per widget id and writes gestures straight back into
+  it. `anchor`, `stretch`, `width` and `height` on `open()` are **initial values** — as rdd's
+  `defaultAnchor`/`defaultStretch` are — so `open()` on an id that is already open refreshes its
+  content and leaves the widget where the user put it, and `close()` then `open()` is what
+  resets placement. No public API changed.
+
+  A port regression: rdd never makes the anchor controllable, and the only placement value it
+  lets a caller control is a primitive, so identity churn cannot arise there. Recorded as **R1**
+  in [`docs/PARITY.md`](docs/PARITY.md), with the underlying `defineModel` constraint amended
+  into [ADR 0005](docs/decisions/0005-vmodel.md). Pinned by PO31–PO35, four M14 gate rules, and
+  a real pointer drag in the demo's browser walkthrough — the gesture path into an overlay-owned
+  widget that no layer of either library's verification had ever driven.
+
+- **In the demo, no camera marker on the main map could be clicked**, though the legend invited
+  it: a decorative polygon added after the markers covered the whole cluster and swallowed every
+  click. It is `interactive: false` now. Found by the new browser assertion trying to open a
+  widget the way a user does.
+
+### Changed
+
+- The demo's camera widgets are opened through `useFloatingWidgets()` instead of a `v-for` over
+  `<VddFloatingWidget>`, so the managed path — the one that regressed — is demonstrated and
+  walked by the gate. The M14 capability rule now requires the composable itself rather than
+  accepting `@update:open`, which is what let the demo claim the capability without exercising
+  it.
+- The M11 browser gate's stretch assertion was measuring the wrong thing: it expected a
+  full-width strip to be `panel - 16` and ignored the inline panel toolbars beside it, so a
+  strip that tracked its panel perfectly was reported as having stopped. It now asserts the
+  tracking claim as a delta and measures the toolbar band. No library behaviour was involved —
+  the failure reproduced identically against 1.0.0's source.
+
 ## [1.0.0] — 2026-09-16
 
 **Parity: react-dockable-desktop 6.3.0.**

package/README.md

@@ -34,7 +34,7 @@ npm install vue-dockable-desktop
 
 Requires Vue 3.4+. No other runtime dependencies. The published package is
 [`vue-dockable-desktop`](https://www.npmjs.com/package/vue-dockable-desktop); the public API
-is pinned by `api-surface.json` and covered by 725 tests.
+is pinned by `api-surface.json` and covered by 730 tests.
 
 ## Quick start
 

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

@@ -22,6 +22,12 @@ type __VLS_ModelProps = {
      *
      * Bind it and the caller owns placement — which is also the only way to persist it, since the
      * library serialises nothing about inner widgets. Leave it off and the widget keeps its own.
+     *
+     * **If you bind it, the value must be stable or echoed back.** `defineModel` re-syncs from the
+     * prop whenever the prop's *identity* changes, so a fresh object literal — `:placement="{ anchor,
+     * stretch }"` — resets the widget on every render of the parent, with or without a listener, and
+     * gestures appear to work and then revert. Hold it in a `ref` and use `v-model:placement`, or
+     * write the emitted value back into whatever you bound.
      */
     'placement'?: PanelFloatPlacement;
 };

package/dist/core/overlayState.d.ts

@@ -17,9 +17,23 @@ export interface ManagedWidget {
     /** Rendered as the widget's content. */
     component: Component;
     props?: Record<string, unknown>;
+    /**
+     * The corner to dock to **on first open**, not live state.
+     *
+     * Seeded into the overlay's own placement record and owned there afterwards, so a gesture
+     * that moves the widget is not undone the next time the caller's state re-renders — and
+     * `open()` on a widget that is already open refreshes its content without yanking it back
+     * to this corner. `close()` then `open()` is what re-seeds it. rdd draws the same line,
+     * with `defaultAnchor` feeding a `useState`.
+     *
+     * @default 'top-right'
+     */
     anchor?: FloatAnchor;
+    /** Initial width in pixels. @default 320 */
     width?: number;
+    /** Initial height in pixels. @default 240 */
     height?: number;
+    /** Which axes span the panel **on first open**. As `anchor`, a seed rather than live state. */
     stretch?: Stretch | null;
 }
 export interface OverlayStacks {
@@ -48,6 +62,15 @@ export interface PanelOverlayStore {
     managed: Map<string, ManagedWidget>;
     /** Bumped whenever `managed` changes, since a `Map` is not reactive by itself. */
     managedVersion: Ref<number>;
+    /**
+     * Live placement of each managed widget, seeded by {@link PanelOverlayStore.openManaged}
+     * from the widget's own `anchor`/`stretch` and owned here from then on.
+     *
+     * Here rather than inside `<VddFloatingWidget>` because a managed widget's `placement` model
+     * has to be *bound* by the overlay — and a bound model is authoritative on every render, so
+     * whatever the overlay binds has to be the live value rather than a re-derived seed.
+     */
+    managedPlacements: Record<string, PanelFloatPlacement>;
     registerToolbar(position: ToolbarPosition, size: number): void;
     unregisterToolbar(position: ToolbarPosition): void;
     focus(id: string): void;
@@ -58,6 +81,8 @@ export interface PanelOverlayStore {
     closeManaged(id: string): void;
     closeAllManaged(): void;
     managedIds(): string[];
+    /** Record what a gesture did to a managed widget's placement. */
+    setManagedPlacement(id: string, placement: PanelFloatPlacement): void;
 }
 export declare const PANEL_OVERLAY_KEY: InjectionKey<PanelOverlayStore>;
 export declare function createPanelOverlayStore(): PanelOverlayStore;