flexdesk 0.17.6 → 0.17.7

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.17.7 (2026-10-24)
+
+A patch release: everything below is additive. Every fix is documented in a
+section of the docs headed "(0.17.7)"; each entry links to it.
+
+### Added and changed
+
+- [`installOverlayScrollbar` is styled by flexdesk.css](docs/components/layout-widgets.md#installoverlayscrollbar-is-styled-by-flexdeskcss-0177): the `.overlay-scrollbar-v` and `.overlay-scrollbar-h` bars that `installOverlayScrollbar` (and `installCollapsibleScrollbars`, `installTabsScrollbars` and `installWorkspaceScrollbars`, which build on it) appends now have rules in flexdesk.css, so they work with only FlexDesk's stylesheets loaded. The bar is `position: absolute` at the container's right or bottom edge, `--scrollbar-size` thick, on `--z-scrollbar`; it starts at `opacity: 0` and shows on hover while the container overflows; it takes no pointer events except on its thumb, which is at least 30px long. Its colours and rounding are the new tokens `--scrollbar-track`, `--scrollbar-thumb`, `--scrollbar-thumb-hover`, `--scrollbar-thumb-active` and `--scrollbar-radius` in tokens.css. Until now no FlexDesk stylesheet styled these classes, so the bar was `position: static`, fed the container's content height and grew it without limit unless the embedder brought its own CSS (BUG-0039).
+
+### Removed or renamed exports
+
+None. Compared with 0.17.6, across every entry point (`core`, `widgets`, `wm`,
+`host`, `canvas`, `flow`, `charts`, `tiles`, `editor`) and the package
+`exports` map, no export was added, removed or renamed. Not an export but
+worth knowing: tokens.css gains the `--scrollbar-*` and `--z-scrollbar`
+custom properties, and flexdesk.css gains rules for `.overlay-scrollbar-v`,
+`.overlay-scrollbar-h` and their `.track` and `.thumb` (see above).
+
 ## 0.17.6 (2026-10-24)
 
 A patch release: everything below is additive. Every fix is documented in a

package/css/base.css

@@ -5969,6 +5969,74 @@ button.twm-about-dialog__btn--close:focus {
 }
 
 
+/* ══ OVERLAY SCROLLBARS (0.17.7) ═════════════════════════════════════
+ *
+ * `installOverlayScrollbar(container, { orientation })`
+ * (src/ui/utils/overlay_scrollbar.js) appends a `.overlay-scrollbar-v` or
+ * `.overlay-scrollbar-h` holding a `.track` and a `.thumb`, and sets their
+ * top/left/height/width from the container's scroll position. The bar is
+ * absolute, so it takes no layout space: a static bar is content, its height
+ * feeds the container's scrollHeight, and the container grows without limit
+ * (BUG-0039). The script sets `data-scrollable` on the container and drives
+ * the bar's opacity and pointer events itself (shown on hover or focus while
+ * the container overflows, kept while the thumb is dragged); these rules are
+ * the hidden starting state, the geometry and the colours. The bar takes no
+ * pointer events, so content under it stays clickable; the thumb takes them
+ * back to be dragged. */
+.overlay-scrollbar-v,
+.overlay-scrollbar-h {
+    position: absolute;
+    pointer-events: none;
+    opacity: 0;
+    transition: opacity var(--transition-fast);
+    z-index: var(--z-scrollbar);
+}
+.overlay-scrollbar-v {
+    top: 0;
+    right: 0;
+    width: var(--scrollbar-size);
+}
+.overlay-scrollbar-h {
+    left: 0;
+    bottom: 0;
+    height: var(--scrollbar-size);
+}
+.overlay-scrollbar-v .track,
+.overlay-scrollbar-h .track {
+    position: absolute;
+    inset: 0;
+    background: var(--scrollbar-track);
+    border-radius: var(--scrollbar-radius);
+}
+.overlay-scrollbar-v .thumb,
+.overlay-scrollbar-h .thumb {
+    position: absolute;
+    background: var(--scrollbar-thumb);
+    border-radius: var(--scrollbar-radius);
+    pointer-events: auto;
+    cursor: pointer;
+    transition: background 80ms ease;
+}
+.overlay-scrollbar-v .thumb {
+    right: 0;
+    width: 100%;
+    min-height: 30px;
+}
+.overlay-scrollbar-h .thumb {
+    bottom: 0;
+    height: 100%;
+    min-width: 30px;
+}
+.overlay-scrollbar-v .thumb:hover,
+.overlay-scrollbar-h .thumb:hover {
+    background: var(--scrollbar-thumb-hover);
+}
+.overlay-scrollbar-v .thumb:active,
+.overlay-scrollbar-h .thumb:active {
+    background: var(--scrollbar-thumb-active);
+}
+
+
 /* ══ RECORD LIST & FACT SHEET (0.7.0) ══════════════════════════════════
  * `createRecordList` (src/ui/components/record_list.js) and
  * `createFactTable` (src/ui/components/fact_table.js). Neither has a height

package/css/flexdesk.css

@@ -9593,6 +9593,74 @@ button.twm-alerts__ref:hover { text-decoration: underline; }
 }
 
 
+/* ══ OVERLAY SCROLLBARS (0.17.7) ═════════════════════════════════════
+ *
+ * `installOverlayScrollbar(container, { orientation })`
+ * (src/ui/utils/overlay_scrollbar.js) appends a `.overlay-scrollbar-v` or
+ * `.overlay-scrollbar-h` holding a `.track` and a `.thumb`, and sets their
+ * top/left/height/width from the container's scroll position. The bar is
+ * absolute, so it takes no layout space: a static bar is content, its height
+ * feeds the container's scrollHeight, and the container grows without limit
+ * (BUG-0039). The script sets `data-scrollable` on the container and drives
+ * the bar's opacity and pointer events itself (shown on hover or focus while
+ * the container overflows, kept while the thumb is dragged); these rules are
+ * the hidden starting state, the geometry and the colours. The bar takes no
+ * pointer events, so content under it stays clickable; the thumb takes them
+ * back to be dragged. */
+.overlay-scrollbar-v,
+.overlay-scrollbar-h {
+    position: absolute;
+    pointer-events: none;
+    opacity: 0;
+    transition: opacity var(--transition-fast);
+    z-index: var(--z-scrollbar);
+}
+.overlay-scrollbar-v {
+    top: 0;
+    right: 0;
+    width: var(--scrollbar-size);
+}
+.overlay-scrollbar-h {
+    left: 0;
+    bottom: 0;
+    height: var(--scrollbar-size);
+}
+.overlay-scrollbar-v .track,
+.overlay-scrollbar-h .track {
+    position: absolute;
+    inset: 0;
+    background: var(--scrollbar-track);
+    border-radius: var(--scrollbar-radius);
+}
+.overlay-scrollbar-v .thumb,
+.overlay-scrollbar-h .thumb {
+    position: absolute;
+    background: var(--scrollbar-thumb);
+    border-radius: var(--scrollbar-radius);
+    pointer-events: auto;
+    cursor: pointer;
+    transition: background 80ms ease;
+}
+.overlay-scrollbar-v .thumb {
+    right: 0;
+    width: 100%;
+    min-height: 30px;
+}
+.overlay-scrollbar-h .thumb {
+    bottom: 0;
+    height: 100%;
+    min-width: 30px;
+}
+.overlay-scrollbar-v .thumb:hover,
+.overlay-scrollbar-h .thumb:hover {
+    background: var(--scrollbar-thumb-hover);
+}
+.overlay-scrollbar-v .thumb:active,
+.overlay-scrollbar-h .thumb:active {
+    background: var(--scrollbar-thumb-active);
+}
+
+
 /* ══ RECORD LIST & FACT SHEET (0.7.0) ══════════════════════════════════
  * `createRecordList` (src/ui/components/record_list.js) and
  * `createFactTable` (src/ui/components/fact_table.js). Neither has a height

package/css/tokens.css

@@ -102,6 +102,14 @@
     --state-active:   rgba(255, 255, 255, 0.08);
     --state-selected: rgba(0, 122, 204, 0.15);
 
+    /* ── Overlay scrollbars (installOverlayScrollbar) ─────────── */
+    --scrollbar-size:         6px;
+    --scrollbar-radius:       3px;
+    --scrollbar-track:        rgba(255, 255, 255, 0.08);
+    --scrollbar-thumb:        rgba(255, 255, 255, 0.28);
+    --scrollbar-thumb-hover:  rgba(255, 255, 255, 0.38);
+    --scrollbar-thumb-active: rgba(255, 255, 255, 0.48);
+
     /* ── Shadows / elevation ──────────────────────────────────── */
     --shadow-sm:   0 1px 3px rgba(0, 0, 0, 0.3);
     --shadow-md:   0 4px 12px rgba(0, 0, 0, 0.4);
@@ -119,6 +127,9 @@
        stack from 6000 to 6999 (managed_window.js), so a popover at
        --z-popover would open behind the window that opened it. */
     --z-over-windows: 7100;
+    /* An overlay scrollbar inside a scroll container: over the container's
+       content and its dropdowns, under managed windows (6000+). */
+    --z-scrollbar: 500;
 
     /* ── Transitions ──────────────────────────────────────────── */
     --transition-fast:   120ms ease;

package/dist/flexdesk.css

@@ -9593,6 +9593,74 @@ button.twm-alerts__ref:hover { text-decoration: underline; }
 }
 
 
+/* ══ OVERLAY SCROLLBARS (0.17.7) ═════════════════════════════════════
+ *
+ * `installOverlayScrollbar(container, { orientation })`
+ * (src/ui/utils/overlay_scrollbar.js) appends a `.overlay-scrollbar-v` or
+ * `.overlay-scrollbar-h` holding a `.track` and a `.thumb`, and sets their
+ * top/left/height/width from the container's scroll position. The bar is
+ * absolute, so it takes no layout space: a static bar is content, its height
+ * feeds the container's scrollHeight, and the container grows without limit
+ * (BUG-0039). The script sets `data-scrollable` on the container and drives
+ * the bar's opacity and pointer events itself (shown on hover or focus while
+ * the container overflows, kept while the thumb is dragged); these rules are
+ * the hidden starting state, the geometry and the colours. The bar takes no
+ * pointer events, so content under it stays clickable; the thumb takes them
+ * back to be dragged. */
+.overlay-scrollbar-v,
+.overlay-scrollbar-h {
+    position: absolute;
+    pointer-events: none;
+    opacity: 0;
+    transition: opacity var(--transition-fast);
+    z-index: var(--z-scrollbar);
+}
+.overlay-scrollbar-v {
+    top: 0;
+    right: 0;
+    width: var(--scrollbar-size);
+}
+.overlay-scrollbar-h {
+    left: 0;
+    bottom: 0;
+    height: var(--scrollbar-size);
+}
+.overlay-scrollbar-v .track,
+.overlay-scrollbar-h .track {
+    position: absolute;
+    inset: 0;
+    background: var(--scrollbar-track);
+    border-radius: var(--scrollbar-radius);
+}
+.overlay-scrollbar-v .thumb,
+.overlay-scrollbar-h .thumb {
+    position: absolute;
+    background: var(--scrollbar-thumb);
+    border-radius: var(--scrollbar-radius);
+    pointer-events: auto;
+    cursor: pointer;
+    transition: background 80ms ease;
+}
+.overlay-scrollbar-v .thumb {
+    right: 0;
+    width: 100%;
+    min-height: 30px;
+}
+.overlay-scrollbar-h .thumb {
+    bottom: 0;
+    height: 100%;
+    min-width: 30px;
+}
+.overlay-scrollbar-v .thumb:hover,
+.overlay-scrollbar-h .thumb:hover {
+    background: var(--scrollbar-thumb-hover);
+}
+.overlay-scrollbar-v .thumb:active,
+.overlay-scrollbar-h .thumb:active {
+    background: var(--scrollbar-thumb-active);
+}
+
+
 /* ══ RECORD LIST & FACT SHEET (0.7.0) ══════════════════════════════════
  * `createRecordList` (src/ui/components/record_list.js) and
  * `createFactTable` (src/ui/components/fact_table.js). Neither has a height

package/dist/tokens.css

@@ -102,6 +102,14 @@
     --state-active:   rgba(255, 255, 255, 0.08);
     --state-selected: rgba(0, 122, 204, 0.15);
 
+    /* ── Overlay scrollbars (installOverlayScrollbar) ─────────── */
+    --scrollbar-size:         6px;
+    --scrollbar-radius:       3px;
+    --scrollbar-track:        rgba(255, 255, 255, 0.08);
+    --scrollbar-thumb:        rgba(255, 255, 255, 0.28);
+    --scrollbar-thumb-hover:  rgba(255, 255, 255, 0.38);
+    --scrollbar-thumb-active: rgba(255, 255, 255, 0.48);
+
     /* ── Shadows / elevation ──────────────────────────────────── */
     --shadow-sm:   0 1px 3px rgba(0, 0, 0, 0.3);
     --shadow-md:   0 4px 12px rgba(0, 0, 0, 0.4);
@@ -119,6 +127,9 @@
        stack from 6000 to 6999 (managed_window.js), so a popover at
        --z-popover would open behind the window that opened it. */
     --z-over-windows: 7100;
+    /* An overlay scrollbar inside a scroll container: over the container's
+       content and its dropdowns, under managed windows (6000+). */
+    --z-scrollbar: 500;
 
     /* ── Transitions ──────────────────────────────────────────── */
     --transition-fast:   120ms ease;

package/docs/components/layout-widgets.md

@@ -36,6 +36,44 @@ at the right edge of a window that was not maximized, so those panes had no
 scrollbar at all (BUG-0036). `tests/autoscroll_resize_handle_not_cover.test.mjs`
 holds it.
 
+## `installOverlayScrollbar` is styled by flexdesk.css (0.17.7)
+
+`installOverlayScrollbar(container, { orientation })` (from
+`@flexdesk/widgets`) gives one container its own bar: a
+`.overlay-scrollbar-v` or `.overlay-scrollbar-h` element, holding a `.track`
+and a `.thumb`, appended to the container (or to its parent with
+`externalBar: true`, as `installTabsScrollbars` does). flexdesk.css styles
+it, so it works with only FlexDesk's stylesheets loaded:
+
+- **It takes no layout space.** The bar is `position: absolute` at the
+  container's right edge (vertical) or bottom edge (horizontal),
+  `--scrollbar-size` thick, on `--z-scrollbar` (over the container's content,
+  under managed windows). The script keeps it pinned to the visible edge as
+  the container scrolls.
+- **It shows on hover while the container overflows.** The script sets
+  `data-scrollable="1"` or `"0"` on the container, and shows the bar on
+  `mouseenter` and `focusin` when it is `"1"`. It hides the bar on leave,
+  unless the thumb is being dragged. The bar starts at `opacity: 0`.
+- **The thumb drags; the rest lets clicks through.** The bar takes no
+  pointer events, so content under it stays clickable. The thumb takes them
+  back (`pointer-events: auto`) and is at least 30px long.
+- **Colours are tokens** in tokens.css: `--scrollbar-track`,
+  `--scrollbar-thumb`, `--scrollbar-thumb-hover`, `--scrollbar-thumb-active`,
+  and `--scrollbar-radius` for the rounding. Override them to restyle every
+  overlay bar.
+
+The rules key on the orientation classes, so a bar created with another
+`className` (`installWorkspaceScrollbars` uses `panel-scrollbar` and
+`tabs-scrollbar`) is styled the same way. `installCollapsibleScrollbars`,
+`installTabsScrollbars` and `installWorkspaceScrollbars` all build on
+`installOverlayScrollbar`, so none of them needs embedder CSS either.
+
+Until 0.17.7 no FlexDesk stylesheet had a rule for these classes. The bar
+was `position: static`: it sat in the scroll container's flow, its height fed
+the container's content height, and the container grew without limit unless
+the embedder brought its own CSS (BUG-0039).
+`tests/overlay_scrollbar_styles.test.mjs` holds it.
+
 ## A stack of collapsible sections: `createSectionStack` (0.17.0)
 
 Inspector-style panel content: titled sections in a column, each opened and

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "flexdesk",
-    "version": "0.17.6",
+    "version": "0.17.7",
     "description": "A tiling window manager and widget set for desktop-class web applications. Zero runtime dependencies.",
     "license": "MIT",
     "repository": {