@webjsdev/ui 0.3.9 → 0.3.11

package/packages/registry/components/dialog.ts

@@ -37,8 +37,28 @@
  * Keyboard: Escape closes (native `cancel` event); Tab cycles trapped
  * within the dialog (native focus trap).
  *
+ * A11y (owned by the element, but SUPPLY A TITLE):
+ *   On open the element names and describes the panel from the
+ *   `data-slot="dialog-title"` / `dialog-description` nodes, falling back to
+ *   the first heading / paragraph. An `aria-label` or `aria-labelledby` you put
+ *   on `<ui-dialog-content>` is forwarded onto the panel and wins over both.
+ *   A modal MUST have an accessible name, so with no title node and no name of
+ *   your own the panel falls back to a generic `aria-label="Dialog"`. That is a
+ *   floor to make an unnamed modal impossible, NOT a substitute: give the
+ *   dialog a real title, since "Dialog" tells a screen reader user nothing
+ *   about what they have been interrupted with.
+ *
  * 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>
@@ -82,18 +102,61 @@ import { buttonClass } from './button.ts';
 // data-slot="dialog-title" (falling back to the first heading); the
 // description is data-slot="dialog-description" (falling back to the first
 // paragraph). Author-set aria-labelledby / aria-describedby always win.
+// The description is independent of the NAME, so it is wired on every path,
+// including the two authored-name early returns below. An author who names the
+// dialog still gets their description node described.
+function wireDialogDescription(host: Element, panel: Element): void {
+  const authored = host.getAttribute('aria-describedby');
+  if (authored) {
+    panel.setAttribute('aria-describedby', authored);
+    return;
+  }
+  const desc =
+    host.querySelector('[data-slot="dialog-description"]') ?? host.querySelector('p');
+  if (desc && !panel.hasAttribute('aria-describedby')) {
+    panel.setAttribute('aria-describedby', ensureId(desc as HTMLElement, 'ui-dialog-desc'));
+  }
+}
+
 export function wireDialogLabels(host: Element, panelSelector: string): void {
   const panel = host.querySelector(panelSelector);
   if (!panel) return;
+  // A name the author put on <ui-dialog-content> is where they naturally write
+  // it, but role="dialog" lives on the inner panel, so forward it there.
+  //
+  // This RETURNS once an authored name is forwarded, rather than falling
+  // through to the title wiring below. Falling through would set
+  // aria-labelledby from the title alongside the forwarded aria-label, and
+  // aria-labelledby beats aria-label per accname, so the title would silently
+  // win over the name the author asked for.
+  const authoredLabelledBy = host.getAttribute('aria-labelledby');
+  if (authoredLabelledBy) {
+    panel.setAttribute('aria-labelledby', authoredLabelledBy);
+    wireDialogDescription(host, panel);
+    return;
+  }
+  const authoredLabel = host.getAttribute('aria-label');
+  if (authoredLabel) {
+    panel.setAttribute('aria-label', authoredLabel);
+    // An authored name replaces the title as the NAME, so any stale
+    // aria-labelledby from an earlier open must go, or it would win over it.
+    panel.removeAttribute('aria-labelledby');
+    wireDialogDescription(host, panel);
+    return;
+  }
   const title =
     host.querySelector('[data-slot="dialog-title"]') ?? host.querySelector('h1, h2, h3');
-  const desc =
-    host.querySelector('[data-slot="dialog-description"]') ?? host.querySelector('p');
   if (title && !panel.hasAttribute('aria-labelledby')) {
     panel.setAttribute('aria-labelledby', ensureId(title as HTMLElement, 'ui-dialog-title'));
   }
-  if (desc && !panel.hasAttribute('aria-describedby')) {
-    panel.setAttribute('aria-describedby', ensureId(desc as HTMLElement, 'ui-dialog-desc'));
+  wireDialogDescription(host, panel);
+  // APG: a modal MUST have an accessible name. Everything above supplies one
+  // only when the author gave the dialog a title node or named it directly, so
+  // a title-less dialog shipped unnamed and was announced as a bare "dialog".
+  // This generic name is a floor, not a substitute for a real title: it makes
+  // an unnamed modal impossible, and a supplied title always wins over it.
+  if (!panel.hasAttribute('aria-labelledby') && !panel.hasAttribute('aria-label')) {
+    panel.setAttribute('aria-label', 'Dialog');
   }
 }
 
@@ -161,30 +224,130 @@ function installStyles(): void {
 }
 
 // --------------------------------------------------------------------------
-// Body scroll lock. Refcounted so nested dialogs unlock in order. Native
-// <dialog> does not lock body scroll, only inert-ifies the background.
+// Page scroll lock, refcounted so nested dialogs release safely in ANY order.
+// Native <dialog> does not lock scrolling, it only inert-ifies the background.
+//
+// Hiding the page scrollbar widens the viewport by the scrollbar's width, so
+// anything laid out against the viewport moves. Padding the page holds in-flow
+// content still, but a `position: fixed` header lays out against the initial
+// containing block, never against any padding box, so padding alone leaves it
+// sliding right by half the scrollbar width. Two mechanisms fix it:
+//
+//   1. Reserve the scrollbar gutter for the duration of the lock, so the
+//      viewport width never changes and NOTHING moves, in flow or fixed. This
+//      needs no cooperation from the page. Measured honoured on Chromium.
+//   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
+//      `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
+// measured residual is zero, so no padding is applied and the custom property is
+// never set: the two mechanisms cannot double-compensate.
 // --------------------------------------------------------------------------
 
-let scrollLockCount = 0;
-let savedOverflow = '';
-let savedPaddingRight = '';
+// The lock's state is DOCUMENT level, so it is keyed on globalThis rather than
+// module scope. dialog.ts and alert-dialog.ts ship as separate copies (so
+// `webjs ui add alert-dialog` stays self contained), and two independent
+// counters mutating the same <html> can only be released safely in LIFO order.
+// They are not: `disconnectedCallback` fires in tree order and the #766
+// before-cache close runs in registration order, so a confirm inside a dialog
+// releases OUTER first, and the inner unlock would then re-apply the values it
+// captured with nothing left to clear them, leaving <html> padded for good. One
+// shared counter makes release order irrelevant.
+interface ScrollLockState {
+  count: number;
+  overflow: string;
+  rootPaddingRight: string;
+  scrollbarGutter: string;
+  compensation: string;
+}
+
+const SCROLLBAR_COMPENSATION = '--wj-scrollbar-compensation';
+
+function scrollLockState(): ScrollLockState {
+  // The key follows the framework's global-key prefix (see `__webjsSonnerBus` in
+  // sonner.ts, the same pattern for the same reason), and the cast is typed
+  // rather than a string-keyed bag, so a change to the shape is a type error in
+  // both copies instead of a silent undefined at runtime.
+  const store = globalThis as unknown as { __webjsScrollLock?: ScrollLockState };
+  let state = store.__webjsScrollLock;
+  if (!state) {
+    state = { count: 0, overflow: '', rootPaddingRight: '', scrollbarGutter: '', compensation: '' };
+    store.__webjsScrollLock = state;
+  }
+  return state;
+}
 
 function lockScroll(): void {
-  if (scrollLockCount === 0) {
-    const scrollbarWidth = window.innerWidth - document.documentElement.clientWidth;
-    savedOverflow = document.body.style.overflow;
-    savedPaddingRight = document.body.style.paddingRight;
-    document.body.style.overflow = 'hidden';
-    if (scrollbarWidth > 0) document.body.style.paddingRight = `${scrollbarWidth}px`;
+  const state = scrollLockState();
+  if (state.count === 0) {
+    const root = document.documentElement;
+    const body = document.body;
+    const rootStyle = getComputedStyle(root);
+
+    state.overflow = body.style.overflow;
+    state.rootPaddingRight = root.style.paddingRight;
+    state.scrollbarGutter = root.style.scrollbarGutter;
+    state.compensation = root.style.getPropertyValue(SCROLLBAR_COMPENSATION);
+
+    // <html> is an in-flow block filling the initial containing block, so its
+    // border box IS the viewport width, and it is re-laid-out synchronously.
+    // A `position: fixed` probe is NOT a substitute: WebKit keeps reporting its
+    // old box until the next rendering update, so it reads a zero delta and the
+    // compensation below never fires.
+    const widthBefore = root.getBoundingClientRect().width;
+    const padBefore = parseFloat(rootStyle.paddingRight) || 0;
+    // An engine with no `scrollbar-gutter` at all reads back undefined, which
+    // must be treated as "the page has not chosen" so the gutter is still
+    // attempted (setting an unsupported property is a harmless no-op, and the
+    // measured residual below is what actually decides the fallback).
+    const chosenGutter = rootStyle.scrollbarGutter || 'auto';
+
+    // Reserve the gutter, but only when the page has not already made its own
+    // choice. An app running `stable both-edges` keeps both gutters through the
+    // lock, and overwriting that with the single-edge value would drop one and
+    // introduce the very shift this exists to prevent.
+    if (chosenGutter === 'auto' && window.innerWidth > root.clientWidth) {
+      root.style.scrollbarGutter = 'stable';
+    }
+    body.style.overflow = 'hidden';
+
+    const grew = root.getBoundingClientRect().width - widthBefore;
+    if (grew > 0) {
+      // Padding the ROOT holds in-flow content still whatever the body's own
+      // width is (a `max-width` body does not widen with the viewport, so
+      // padding the body would miss it), and it leaves the page's own body
+      // padding untouched.
+      root.style.paddingRight = `${padBefore + grew}px`;
+      // A fixed box lays out against the viewport, so no padding here can reach
+      // it. Publish what it moved by and let it opt in.
+      root.style.setProperty(SCROLLBAR_COMPENSATION, `${grew}px`);
+    }
   }
-  scrollLockCount++;
+  state.count++;
 }
 
 function unlockScroll(): void {
-  scrollLockCount = Math.max(0, scrollLockCount - 1);
-  if (scrollLockCount === 0) {
-    document.body.style.overflow = savedOverflow;
-    document.body.style.paddingRight = savedPaddingRight;
+  const state = scrollLockState();
+  // An unlock with no matching lock is a no-op, NOT the last release: clamping to
+  // zero and restoring would replay a stale snapshot onto whatever the page owns
+  // now. Belt-and-braces as things stand, because _teardown() only unlocks what
+  // its own element locked, so no path through the components can reach here with
+  // a zero count. It is kept because the cost is one comparison and the failure
+  // it prevents is silent.
+  if (state.count === 0) return;
+  state.count--;
+  if (state.count === 0) {
+    const root = document.documentElement;
+    document.body.style.overflow = state.overflow;
+    root.style.paddingRight = state.rootPaddingRight;
+    root.style.scrollbarGutter = state.scrollbarGutter;
+    // Restored rather than removed, so a value the PAGE set before any dialog
+    // opened survives the lock.
+    if (state.compensation) root.style.setProperty(SCROLLBAR_COMPENSATION, state.compensation);
+    else root.style.removeProperty(SCROLLBAR_COMPENSATION);
   }
 }
 
@@ -205,6 +368,7 @@ export class UiDialog extends WebComponent({
   }
 
   _disposeBeforeCache?: () => void;
+  _scrollLocked?: boolean;
 
   connectedCallback(): void {
     installStyles();
@@ -258,14 +422,33 @@ export class UiDialog extends WebComponent({
   }
 
   _setup(): void {
+    // A detached element must not lock: `updated()` defers this to a microtask,
+    // and a removal in between already ran _teardown() as a no-op, so locking
+    // here would never be released (nothing disconnects twice).
+    if (!this.isConnected) return;
     const content = this._content;
     if (!content) return;
-    lockScroll();
+    // Idempotent, because the count is an integer and the flag is a boolean. A
+    // coalesced hide() then show() in one task produces ONE update whose
+    // changedProperties still reports open, so _setup() can run twice with no
+    // _teardown() between; double-counting there would leave the page locked for
+    // the rest of the session.
+    if (!this._scrollLocked) {
+      lockScroll();
+      this._scrollLocked = true;
+    }
     content.showModal();
   }
 
   _teardown(): void {
-    unlockScroll();
+    // Release only what THIS element locked. _setup() returns before locking
+    // when there is no content child, so an unconditional unlock here would
+    // consume ANOTHER open dialog's count and restore the page out from under
+    // it, dropping its compensation while it is still open.
+    if (this._scrollLocked) {
+      this._scrollLocked = false;
+      unlockScroll();
+    }
     this._content?.close();
   }
 }