fix(ui): bring the blog's lock copy fully in lockstep, unrig two tests

vivek7405 · vivek7405 · commit 62d1bede8576 · 2026-07-28T04:21:59.000+05:30
The blog copy's lock banner still prescribed the padding form that was removed
for cause, which made it the one line out of step across the three copies and the
only place a reader was pointed at the rejected approach. It also lacked the
scroll-lock paragraph the registry copies carry in their module JSDoc. The
executable block was already byte-identical and stays so.

Two tests were claiming more than they proved. The SSR placement check asserted
that no rule targets `.site-bar`, a class that no longer exists anywhere, so it
could never fail; it now asserts exactly one rule consumes the property, which
also catches the unclassed centring div that no selector-based check can name.
And the contentless-dialog test was named and explained after a path the
`_scrollLocked` guard made unreachable, presenting a defensive branch as the
thing under test; it now says what it actually pins, and says plainly that
deleting the count-zero early return would leave it green.
diff --git a/examples/blog/components/ui/dialog.ts b/examples/blog/components/ui/dialog.ts
@@ -62,6 +62,46 @@
  * within the dialog (native focus trap).
  *
  * Design tokens used: --background, --border, --muted-foreground.
+ *
+ * Scroll lock (#1144): opening the dialog locks body scroll, which hides the
+ * page scrollbar and would widen the viewport. The lock reserves the scrollbar
+ * gutter so the width never changes and a `position: fixed` header stays put.
+ * Where the engine ignores `scrollbar-gutter` (WebKit today) it publishes the
+ * leftover width on <html> as `--wj-scrollbar-compensation`, so a fixed header
+ * opts in with `border-right: var(--wj-scrollbar-compensation, 0px) solid transparent`
+ * (a transparent border composes with existing padding, and a background paints
+ * across it, so a header keeps its own chrome full bleed).
+ *
+ * @example
+ * ```html
+ * <ui-dialog>
+ *   <ui-dialog-trigger>
+ *     <button class=${buttonClass({ variant: 'outline' })}>Edit profile</button>
+ *   </ui-dialog-trigger>
+ *   <ui-dialog-content>
+ *     <div class=${dialogHeaderClass()}>
+ *       <h2 data-slot="dialog-title" class=${dialogTitleClass()}>Edit profile</h2>
+ *       <p data-slot="dialog-description" class=${dialogDescriptionClass()}>Make changes and click save.</p>
+ *     </div>
+ *     <div class="grid gap-3">
+ *       <label class=${labelClass()} for="dlg-name">Name</label>
+ *       <input class=${inputClass()} id="dlg-name" placeholder="Your name">
+ *     </div>
+ *     <div class=${dialogFooterClass()}>
+ *       <ui-dialog-close><button class=${buttonClass({ variant: 'outline' })}>Cancel</button></ui-dialog-close>
+ *       <button class=${buttonClass()}>Save</button>
+ *     </div>
+ *   </ui-dialog-content>
+ * </ui-dialog>
+ *
+ * <!-- Suppress the auto-injected top-right X close button. -->
+ * <ui-dialog-content show-close-button="false">
+ *   <div class=${dialogHeaderClass()}>
+ *     <h2 data-slot="dialog-title" class=${dialogTitleClass()}>Quiet dialog</h2>
+ *   </div>
+ * </ui-dialog-content>
+ * ```
+
  */
 import { WebComponent, html, unsafeHTML, prop } from '@webjsdev/core';
 import { ref, createRef } from '@webjsdev/core/directives';
@@ -137,7 +177,7 @@ function installStyles(): void {
 //   2. Where the engine ignores it (measured on WebKit), fall back to
 //      padding <html> and publish the leftover width as
 //      `--wj-scrollbar-compensation` on it, so a fixed element can opt in with
-//      `padding-right: var(--wj-scrollbar-compensation, 0px)`.
+//      `border-right: var(--wj-scrollbar-compensation, 0px) solid transparent`.
 //
 // Everything below is MEASURED rather than assumed, because engines disagree
 // about both scrollbar geometry and gutter support. When mechanism 1 works the
diff --git a/packages/ui/test/components/browser/ui-overlay.test.js b/packages/ui/test/components/browser/ui-overlay.test.js
@@ -463,12 +463,17 @@ suite('ui-dialog scroll lock layout', () => {
     }
   });
 
-  // A dialog with no content child returns from _setup() BEFORE locking, but
-  // _teardown() unlocks unconditionally, so an unlock can arrive with no lock
-  // behind it. Treating that as the last release would replay a stale snapshot
-  // onto whatever the page owns now, and while another dialog is open it would
-  // drop that dialog's compensation mid-flight.
-  test('an unlock with no matching lock does not disturb an open dialog', async function () {
+  // A dialog with no content child returns from _setup() BEFORE locking, so it
+  // must not release anything on the way out. It used to: _teardown() unlocked
+  // unconditionally, which consumed the OPEN dialog's refcount and restored the
+  // page mid-flight, dropping its compensation.
+  //
+  // What this pins is the `_scrollLocked` guard in _teardown(). The count-zero
+  // early return in unlockScroll() is now belt-and-braces rather than the thing
+  // under test, because no path through the components can reach unlockScroll
+  // with a zero count any more. Deleting that early return would leave this
+  // green, and that is expected.
+  test('a contentless dialog does not release an open dialog\'s lock', async function () {
     const page = await buildFixedHeaderPage();
     try {
       if (!requireClassicScrollbar(this)) return;
diff --git a/website/test/ssr/fixed-header-scroll-lock.test.ts b/website/test/ssr/fixed-header-scroll-lock.test.ts
@@ -68,13 +68,23 @@ test('the compensation targets the header, not the wrapper or the centring bar',
     new RegExp(`\\.site-top\\s*>\\s*header\\s*\\{[^}]*var\\(${COMPENSATION}`).test(body),
     'a `.site-top > header` rule consumes the compensation',
   );
-  for (const wrong of ['\\.site-top', '\\.site-bar']) {
-    assert.equal(
-      new RegExp(`${wrong}\\s*\\{[^}]*var\\(${COMPENSATION}`).test(body),
-      false,
-      `${wrong.replace('\\', '')} must not be the element inset`,
-    );
-  }
+  // `.site-top` on its own is the wrong target and IS a reachable mistake, since
+  // it is the fixed element and the obvious thing to reach for.
+  assert.equal(
+    new RegExp(`\\.site-top\\s*\\{[^}]*var\\(${COMPENSATION}`).test(body),
+    false,
+    'the non-painting fixed wrapper must not be the element inset',
+  );
+  // Exactly ONE rule may consume it. The other wrong target was the centring
+  // div, which carries no class, so it cannot be named in a negative selector
+  // check; counting the consuming rules catches it anyway, and catches any future
+  // second consumer that would double-compensate.
+  const consumers = body.match(new RegExp(`\\{[^{}]*var\\(${COMPENSATION}`, 'g')) ?? [];
+  assert.equal(
+    consumers.length,
+    1,
+    `exactly one rule may consume the compensation, found ${consumers.length}`,
+  );
 });
 
 test('the compensation resolves to zero when no lock is active', () => {
