vue-dockable-desktop 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -11,6 +11,162 @@ correspondence lives, alongside the feature-by-feature map in [docs/PARITY.md](d
 
 ## [Unreleased]
 
+## [1.4.0] — 2026-09-30
+
+**Parity: react-dockable-desktop 6.3.1, plus react-dockable-desktop 7.2.0 and 7.3.0's skin
+branding.** Branding, part two: your own surfaces and corner shape on any built-in skin. See
+[Your surfaces](docs/manual/10-theming.md#your-surfaces) and [Corners](docs/manual/10-theming.md#corners).
+
+### Added
+
+- **`--vdd-brand-surface`** and **`--vdd-brand-text`**: set per scheme on `:root`, they replace
+  every built-in skin's backgrounds and text — the workspace, panels, tab bar, sidebar, floating
+  windows, modals, drawers, the taskbar, toasts, borders and muted text are all derived from the
+  two. Set both or neither: with only one set, every skin keeps its own surfaces. A skin keeps
+  its shape and effects (macOS's glass, Chrome's tabs, the VS Code accent bar) and each
+  translucent surface keeps the skin's own transparency; the accent, status colours and shadows
+  are not affected.
+- **`--vdd-radius-scale`**: multiplies every corner the library draws — `0` square, `1` each
+  skin's own (the default), `1.5` rounder. Circles and pills stay round. It also scales the
+  radius tokens you set yourself (`--vdd-panel-float-radius`, `--vdd-panel-toolbar-btn-radius`,
+  `--vdd-tab-btn-active-radius`).
+- Manual: **Your surfaces** and **Corners** under Brand your app, the corner habit for custom
+  skins, and the three variables in the token reference.
+
+### Fixed
+
+- **The workspace-edge drop preview was Bootstrap blue** (`#007bff`) in every skin, instead of
+  the skin's accent. It follows `--vdd-accent-color` and `--vdd-brand-accent` now. It shows only
+  while you drag a panel to a workspace edge.
+- **Colours no token reached**: the dock-target chips, the light-mode outline button (the
+  confirm dialog's Cancel) and the frosted panel toolbar painted literal colours in their own
+  rules. They read the surface tokens now, and follow a brand surface; unbranded they are
+  unchanged.
+
+### Tests
+
+- **M16 browser gate** (`scripts/gates/browser/m16.mjs`, real Chrome): the corner radii of every
+  library element and pseudo-element, in all 7 skins × dark/light, match a 1.3.0 baseline with
+  the scale unset, are `0px` at scale `0` and 1.5× at `1.5`, with circles and pills unchanged;
+  with a brand surface set, no colour of any skin's own palette remains — rendered, hovered or as
+  a token — the workspace, panel and tab bar stay distinct, and text on panels meets 4.5:1
+  (muted 3:1); with only one of the two set, a scene matches M15's baseline. M15's gate still
+  holds with no brand set.
+- `test/core/stylesheet.test.ts`, ported from rdd 7.3.0: every corner length is scaled and the
+  library never declares the scale; every coloured surface reads a derived value first, declared
+  only on `:root` and built on the guarded base; no element rule paints a colour of its own.
+- M16 rules (`scripts/gates/m16.mjs`) and two selftest cases. The M15 browser gate's scene
+  helpers moved to `scripts/gates/lib/branding-scenes.mjs`, shared with M16. The playground
+  takes `?bs=`, `?bt=` and `?rs=`.
+
+### Documentation
+
+- Theming chapter: Your surfaces, Corners, the fourth brandable-skin habit, token rows; README
+  snippet; ADR 0018; PARITY.md; the plan's M16.
+
+## [1.3.0] — 2026-09-29
+
+**Parity: react-dockable-desktop 6.3.1, plus react-dockable-desktop 7.2.0's skin branding**
+(the same port angular-dockable-desktop 1.1.0 made). Put your company's colour and font on any
+built-in skin with a few CSS variables — no skin of your own needed. See
+[Brand your app](docs/manual/10-theming.md#brand-your-app).
+
+### Added
+
+- **`--vdd-brand-accent`**: set on `:root`, it replaces the accent of every built-in skin in dark
+  and light — tab indicators, active sidebar tabs and toolbar buttons, hover and active tints,
+  glows, the focused window's glow, the taskbar, the drop and snap highlights, the primary
+  button. Unset, each skin keeps its own accent.
+- **`--vdd-brand-on-accent`**: the text colour on a solid accent fill (the confirm dialog's
+  primary button, the highlighted dock target), for light brand colours such as yellow — in both
+  schemes. Defaults as before: `#090b11`, and `#ffffff` on the primary button in light mode.
+- **Per-skin fonts** through `--vdd-skin-font-family`: `vscode` uses VS Code's workbench font,
+  `macos` San Francisco, `chrome` Google's UI fonts, `slate` Fluent's Segoe UI stack, `nord` a
+  humanist sans (Avenir Next) and `tokyo` a monospace (JetBrains Mono); `obsidian` keeps the
+  library stack. All are system font stacks — the library still loads no fonts — and your own
+  `--vdd-font-family` replaces them all, teleported chrome included. `:root` now declares
+  `--vdd-font-family` as `var(--vdd-skin-font-family, 'Outfit', 'Inter', system-ui,
+  -apple-system, sans-serif)`.
+- Manual: **Brand your app** — the brand variables, a per-scheme brand colour, loading your own
+  font, following a UI framework's theme (PrimeVue, Bootstrap, Tailwind, shadcn-vue), where to
+  put a logo (a custom `headerAction` entry on `<VddSidebar>`), and how to keep a custom skin
+  brandable.
+
+### Changed
+
+- **Browser minimum**: CSS `color-mix()` — Chrome / Edge 111, Safari 16.2, Firefox 113 (all
+  2023). In an older browser the tinted hover and active highlights lose their colour; layout and
+  behaviour are unaffected.
+- **The default skin's font** is VS Code's workbench stack (`-apple-system, BlinkMacSystemFont,
+  'Segoe WPC', 'Segoe UI', …`) instead of `'Outfit', 'Inter', …`, which is now the fallback for
+  skins that set no font (`obsidian`, and custom skins). If you loaded Outfit for the library,
+  set `--vdd-font-family` to it. In `tokyo`, `nord`, `macos`, `chrome` and `slate` the font changes
+  too — and panel content inherits it, so in `tokyo` your panels turn monospace unless they set a
+  font of their own.
+- **Every tint of the accent is derived from it** (`color-mix()` of `--vdd-accent-color`) instead
+  of a hand-copied `rgba()`. With the built-in skins and no brand set, the look is unchanged
+  except for the fixes below.
+- `vscode` light mode has an accent of its own, `#0066cc` — the blue its light-mode tokens
+  already used. The primary button, the taskbar's peek handle and the other accent uses, which
+  were cyan on a light background, are that blue now. A custom skin that sets no accent gets it
+  in light mode too.
+- **Set the accent with `--vdd-brand-accent`, not `--vdd-accent-color`.** Every skin and the light
+  scheme declare `--vdd-accent-color` with a selector that also matches the workspace element, so
+  a `:root` override of it is replaced inside the workspace — now in `vscode` light mode as well,
+  where 1.2.0 had no light accent to replace it with.
+
+### Fixed
+
+- **Overriding `--vdd-accent-color` on `:root` had no effect in 6 of the 7 skins**: each skin
+  redeclared it on the workspace element. `--vdd-brand-accent`, which every skin reads first, is
+  the supported way to rebrand.
+- **Changing the accent left the old colour behind**: 142 hover, active and glow colours were
+  copies of a skin's accent written as fixed `rgba()` values. They follow the accent now.
+- **Skins showed colours that weren't theirs**: the default cyan (and `#0066cc` in light mode)
+  left in other skins — the taskbar hover glow, the dock preview and corner-snap highlights, the
+  floating-widget drop zones, the light-mode focused-tab indicator and taskbar text, the
+  `--vdd-sidebar-card-*` and `--vdd-sidebar-btn-front-*` tokens — now show each skin's own
+  accent. `slate` and `tokyo` drew their active states in a blue that wasn't their accent, and
+  `obsidian`'s panel toolbar in a violet; they use their accent now. `obsidian`'s dark-mode white
+  glows no longer show in light mode, where its accent is black.
+- **The rail and toolbar buttons ignored `--vdd-font-family`**: a `<button>` does not inherit a
+  font, so they drew their labels and badges in the browser's button font (Arial in Chrome) in
+  every skin. The library's own form controls inherit the chrome font now, as in rdd 6.4.0; your
+  own inputs and buttons inside a panel are left alone. Found by the M15 font check.
+
+### Tests
+
+- **M15 browser gate** (`scripts/gates/browser/m15.mjs`, real Chrome): with no brand set, the
+  computed colours of every library element, its pseudo-elements, 8 hover states and every token
+  (inside the workspace, in the toolbar outside it, and on `<body>`), in all 7 skins × dark/light
+  with the chrome opened, match a 1.2.0 baseline — except exactly the fixes above; with a brand
+  set, no trace of any original accent remains; a light brand with a dark on-accent colour is
+  readable on the primary button in dark and light; each skin's font reaches every piece of
+  chrome, and a brand font set on `:root` wins in every skin, teleported chrome included. Its
+  `--control` run (a skin that redeclares its accent and its font) is rejected.
+- `test/core/stylesheet.test.ts`, ported from rdd 7.2.0's branding contract: every
+  `--vdd-accent-color` reads `--vdd-brand-accent` first, nothing in the library declares a
+  `--vdd-brand-*` variable, no accent colour is written as a literal outside its one declaration,
+  only `:root` declares `--vdd-font-family`, and text on accent fills reads
+  `--vdd-brand-on-accent`.
+- M15 rules (`scripts/gates/m15.mjs`): the release files, ADR 0017, the manual's skin-font table
+  against the stylesheet, the browser minimum in the README and chapter 1, and PARITY.md.
+- The playground takes `?skin=`, `?cs=light`, `?ba=` / `?bon=` (brand variables before mount)
+  and `?anim=0`.
+- **The gate runner no longer mistakes another app for its own**: with another dev server on
+  the demo's port, `--strictPort` stopped vdd's demo from starting, the runner took the other
+  app's answer as ready, and M14 timed out waiting for the demo. It now waits for its own Vite's
+  ready line, moves to the next free port when the usual one is taken, and passes the URL to the
+  browser gates (`VDD_APP_URL`; the usual ports stay the default when a gate is run by hand).
+
+### Documentation
+
+- Theming chapter: **Brand your app**, **Skin fonts**, brandable custom skins (the demo's `mono`
+  skin now reads `--vdd-brand-accent` too), and the token reference (a branding table; tints
+  listed as "the accent at N%").
+- The browser minimum in the README and chapter 1; a Branding item in the README's features;
+  the rdd 7.2.0 names in the migration chapter; ADR 0017; PARITY.md.
+
 ## [1.2.0] — 2026-09-24
 
 **Parity: react-dockable-desktop 6.3.1.**

package/README.md

@@ -23,8 +23,8 @@ so a layout saved by either library loads in the other.
 > **Versioning.** vdd follows its own semver, independently of `react-dockable-desktop`:
 > matching the two numbers would be a promise that breaks the first time either library needs
 > a breaking change the other does not. Which rdd release a given version corresponds to is
-> stated per release in [CHANGELOG.md](CHANGELOG.md) — this one tracks **rdd 6.3.0** — and
-> feature by feature in [docs/PARITY.md](docs/PARITY.md).
+> stated per release in [CHANGELOG.md](CHANGELOG.md) — this one tracks **rdd 6.3.1**, plus
+> rdd 7.2.0 and 7.3.0's skin branding — and feature by feature in [docs/PARITY.md](docs/PARITY.md).
 
 ## Install
 
@@ -32,9 +32,10 @@ so a layout saved by either library loads in the other.
 npm install vue-dockable-desktop
 ```
 
-Requires Vue 3.4+. No other runtime dependencies. The published package is
+Requires Vue 3.4+, and a browser with CSS `color-mix()` (Chrome / Edge 111, Safari 16.2,
+Firefox 113 or later). 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 730 tests.
+is pinned by `api-surface.json` and covered by 851 tests.
 
 ## Quick start
 
@@ -103,7 +104,30 @@ localStorage.setItem('layout', ws.saveLayout())
 - **Panel overlay** — anchored toolbars and floating widgets inside a single panel
 - **Overlays** — side panels, a modal stack, dirty-close confirmation, and toasts
 - **Layout serialisation** — save and restore the whole workspace as a JSON string
-- **Theming** — built-in skins, light/dark colour schemes, all `--vdd-*` CSS variables
+- **Theming** — built-in skins, each with its own font, light/dark colour schemes, all
+  `--vdd-*` CSS variables
+- **Branding** — your company's colour and font on any built-in skin, from three variables:
+
+  ```css
+  :root {
+    --vdd-brand-accent: #e4002b;                 /* every accent use, in every skin, dark and light */
+    --vdd-brand-on-accent: #ffffff;              /* text on a brand-coloured fill — a dark one for light brands */
+    --vdd-font-family: 'Acme Sans', sans-serif;  /* your font (the library loads none) */
+  }
+  ```
+
+  Point them at your UI framework's theme to follow it — `var(--p-primary-color)` (PrimeVue),
+  `var(--bs-primary)` (Bootstrap). Your own surfaces and corner shape, too:
+
+  ```css
+  :root:not([data-color-scheme="light"]) {  /* dark: the attribute's absence */
+    --vdd-brand-surface: #0b1f3a;   /* app background — panels, bars and borders derive from it */
+    --vdd-brand-text: #e8eef7;      /* main text — set both, or neither */
+  }
+  :root { --vdd-radius-scale: 0; }  /* 0 square · 1 each skin's own · 1.5 rounder */
+  ```
+
+  See [Brand your app](docs/manual/10-theming.md#brand-your-app)
 - **i18n and RTL** — every string is a message key; `dir="rtl"` flips the whole workspace
 - **TypeScript-first** — complete types, no separate `@types` package