@jungherz-de/glasskit-elements 1.19.2 → 1.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jungherz-de/glasskit-elements",
-  "version": "1.19.2",
+  "version": "1.21.0",
   "description": "Vanilla JavaScript Web Components wrapping the GlassKit CSS glassmorphism library",
   "license": "MIT",
   "homepage": "https://glasskit-elements.jungherz.com",
@@ -49,10 +49,10 @@
     "vanilla-js"
   ],
   "peerDependencies": {
-    "@jungherz-de/glasskit": ">=1.19.1"
+    "@jungherz-de/glasskit": ">=1.21.0"
   },
   "devDependencies": {
-    "@jungherz-de/glasskit": "^1.19.1",
+    "@jungherz-de/glasskit": "^1.21.0",
     "@rollup/plugin-node-resolve": "^15.0.0",
     "@rollup/plugin-terser": "^0.4.0",
     "rollup": "^4.0.0"

package/src/base.js

@@ -11,25 +11,58 @@ import { componentsSheet, tokensCss } from '@jungherz-de/glasskit/glasskit-style
 // inherits them like any other custom property. They are wrapped in a cascade
 // layer so an ordinary (unlayered) brand stylesheet wins over them, no matter
 // whether it loads before or after this module.
+//
+// Only the custom properties go there. GlassKit's token blocks also set
+// color-scheme, and on the document that is no default: it switches the whole
+// page to dark — native controls, scrollbars, the root text colour, link
+// colours — on pages that never asked for GlassKit's theme. The elements set
+// color-scheme on their own theme wrapper instead (host sheet below).
+//
+// The --gl-* names themselves are still global. A page that declares them
+// itself, or wants them on part of the page only, switches the defaults off
+// with <html data-glk-defaults="off">. The attribute is watched, so it may
+// also be set or removed later.
 
 const TOKENS_INJECTED = '__glkDefaultTokensInjected';
+const DEFAULTS_ATTR = 'data-glk-defaults';
+let defaultTokensSheet = null;
 
 function injectDefaultTokens() {
   if (typeof document === 'undefined') return;              // SSR / non-DOM
   if (globalThis[TOKENS_INJECTED]) return;                   // another bundle copy did it
   globalThis[TOKENS_INJECTED] = true;
 
-  const sheet = new CSSStyleSheet();
-  sheet.replaceSync(`@layer glasskit-defaults { ${tokensCss} }`);
-  // Append — never assign — so an app's own adopted sheets survive.
-  document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];
+  const tokens = tokensCss.replace(/color-scheme\s*:[^;}]*;?/g, '');
+  defaultTokensSheet = new CSSStyleSheet();
+  defaultTokensSheet.replaceSync(`@layer glasskit-defaults { ${tokens} }`);
+  syncDefaultTokens();
+}
+
+/** Adopts or drops the default tokens to match <html data-glk-defaults>. */
+function syncDefaultTokens() {
+  if (!defaultTokensSheet) return;
+  const wanted = document.documentElement.getAttribute(DEFAULTS_ATTR) !== 'off';
+  const sheets = document.adoptedStyleSheets;
+  if (wanted === sheets.includes(defaultTokensSheet)) return;
+  // Add or remove only this sheet — never assign a fresh list — so an app's
+  // own adopted sheets survive.
+  document.adoptedStyleSheets = wanted
+    ? [...sheets, defaultTokensSheet]
+    : sheets.filter(sheet => sheet !== defaultTokensSheet);
 }
 
 injectDefaultTokens();
 
-// ── Global Theme Sync ──
-// Single MutationObserver that watches data-theme on <html>
+// ── Global Theme & Density Sync ──
+// Single MutationObserver that watches data-theme and data-density on <html>
 // and notifies all GlkElement instances.
+//
+// The density tokens themselves arrive from <html> by inheritance, like every
+// other token: GlassKit's [data-density="compact"] preset is part of
+// tokensCss, not of the components sheet. The wrapper mirrors the attribute
+// anyway, as it mirrors data-theme — a rule keyed on it (a component rule, a
+// subclass's hostStyles) can match inside a shadow root only on an element
+// there.
 
 const instances = new Set();
 
@@ -37,6 +70,11 @@ function getCurrentTheme() {
   return document.documentElement.getAttribute('data-theme') || 'dark';
 }
 
+/** The density on <html>, or null — there is no default to fall back to. */
+function getCurrentDensity() {
+  return document.documentElement.getAttribute('data-density');
+}
+
 function syncAllThemes() {
   const theme = getCurrentTheme();
   for (const instance of instances) {
@@ -44,32 +82,103 @@ function syncAllThemes() {
   }
 }
 
+function syncAllDensities() {
+  const density = getCurrentDensity();
+  for (const instance of instances) {
+    instance._syncDensity(density);
+  }
+}
+
 if (typeof window !== 'undefined' && typeof MutationObserver !== 'undefined') {
-  const observer = new MutationObserver(syncAllThemes);
+  const observer = new MutationObserver(records => {
+    if (records.some(r => r.attributeName === 'data-theme')) syncAllThemes();
+    if (records.some(r => r.attributeName === 'data-density')) syncAllDensities();
+    if (records.some(r => r.attributeName === DEFAULTS_ATTR)) syncDefaultTokens();
+  });
   observer.observe(document.documentElement, {
     attributes: true,
-    attributeFilter: ['data-theme']
+    attributeFilter: ['data-theme', 'data-density', DEFAULTS_ATTR]
   });
 }
 
 // ── Host Stylesheet ──
 // Sets display:block on all custom elements by default.
 // Inline components (badge, avatar) override this.
+//
+// The wrapper carries the theme's color-scheme, so native parts inside the
+// elements — a select's list, a date picker, scrollbars — match the element,
+// whatever the page around it uses.
+
+const wrapperRules = `
+  .glk-wrapper { display: contents; }
+  .glk-wrapper[data-theme="dark"] { color-scheme: dark; }
+  .glk-wrapper[data-theme="light"] { color-scheme: light; }
+`;
 
 const hostSheet = new CSSStyleSheet();
 hostSheet.replaceSync(`
   :host { display: block; }
   :host([hidden]) { display: none; }
-  .glk-wrapper { display: contents; }
+  ${wrapperRules}
 `);
 
 const inlineHostSheet = new CSSStyleSheet();
 inlineHostSheet.replaceSync(`
   :host { display: inline-block; }
   :host([hidden]) { display: none; }
-  .glk-wrapper { display: contents; }
+  ${wrapperRules}
 `);
 
+/**
+ * Host rules for glk-checkbox, glk-radio and glk-toggle. Their control is an
+ * inline-flex label inside a block host; sitting on the text baseline it left
+ * room for descenders below, so the host was about 4px taller than the
+ * control and the control sat high in a centred row. Aligned to the top of
+ * its line, the label is as tall as the host.
+ */
+export const checkControlSheet = new CSSStyleSheet();
+checkControlSheet.replaceSync(`
+  .glass-checkbox, .glass-radio, .glass-toggle { vertical-align: top; }
+`);
+
+// ── Clicks Aimed at the Host ──
+// The innermost target of the latest pointerdown anywhere in the document;
+// tracked once, on first use.
+let lastPressed = null;
+let trackingPresses = false;
+
+/**
+ * For elements whose control is a native input or button inside the shadow
+ * root: glk-checkbox, glk-radio, glk-toggle, glk-button. A click aimed at the
+ * host itself — host.click(), or the click a <label> around the element or
+ * naming it dispatches — reaches only the host. The control never saw it, so
+ * nothing changed where a native checkbox toggles and a native button
+ * submits. Such a click is handed to the control; the original is stopped, so
+ * listeners see one click, the control's.
+ *
+ * A pointer press on the host's own empty box (the host is a block, the
+ * control is narrower) also lands on the host. Chrome cannot tell it apart
+ * from a label's click by the event, only by where the pointer went down; it
+ * stays a no-op, as before. Returns the teardown.
+ */
+export function forwardHostClicks(host, getField) {
+  if (!trackingPresses && typeof window !== 'undefined') {
+    trackingPresses = true;
+    window.addEventListener('pointerdown', e => { lastPressed = e.composedPath()[0]; },
+      { capture: true, passive: true });
+  }
+  const onClick = (e) => {
+    if (e.composedPath()[0] !== host) return;           // from inside: the input had it
+    if (e.isTrusted && lastPressed === host) return;     // a press on the empty box
+    const field = getField();
+    if (!field || field.disabled) return;
+    e.stopImmediatePropagation();
+    field.click();
+  };
+  host.addEventListener('click', onClick);
+  return () => host.removeEventListener('click', onClick);
+}
+
 // ── Base Class ──
 
 export class GlkElement extends HTMLElement {
@@ -92,6 +201,13 @@ export class GlkElement extends HTMLElement {
    */
   static get observesLightDom() { return false; }
 
+  /**
+   * Turned on by elements built around one native field: focus() on the
+   * host, a click on the label text and a <label for> outside all land in
+   * that field.
+   */
+  static get delegatesFocus() { return false; }
+
   static get observedAttributes() {
     return [];
   }
@@ -99,7 +215,7 @@ export class GlkElement extends HTMLElement {
   constructor() {
     super();
     this._initialized = false;
-    this._shadow = this.attachShadow({ mode: 'open' });
+    this._shadow = this.attachShadow({ mode: 'open', delegatesFocus: this.constructor.delegatesFocus });
     const displaySheet = this.constructor.displayInline ? inlineHostSheet : hostSheet;
     const sheets = [componentsSheet, displaySheet];
     const extra = this.constructor.hostStyles;
@@ -115,9 +231,17 @@ export class GlkElement extends HTMLElement {
       this._wrapper = document.createElement('div');
       this._wrapper.className = 'glk-wrapper';
       this._wrapper.setAttribute('data-theme', getCurrentTheme());
+      this._syncDensity(getCurrentDensity());
       this._shadow.appendChild(this._wrapper);
 
       this.render();
+    } else {
+      // Back in the document. While it was out, the observer did not reach
+      // it, so a theme or density switched in the meantime is caught up here
+      // — the wrapper's data-theme also sets the color-scheme of the native
+      // parts inside.
+      this._syncTheme(getCurrentTheme());
+      this._syncDensity(getCurrentDensity());
     }
 
     // Everything below runs on every connect, not just the first. Moving an
@@ -153,6 +277,16 @@ export class GlkElement extends HTMLElement {
     }
   }
 
+  /** Mirrors data-density from <html>; without one there, the wrapper has none. */
+  _syncDensity(density) {
+    if (!this._wrapper) return;
+    if (density) {
+      this._wrapper.setAttribute('data-density', density);
+    } else {
+      this._wrapper.removeAttribute('data-density');
+    }
+  }
+
   /** Subclasses override to build inner DOM inside this._wrapper. */
   render() {}
 
@@ -240,14 +374,26 @@ export class GlkFormElement extends GlkElement {
 
   static formAssociated = true;
 
+  // One native field inside, so focus goes there. The button groups
+  // (glk-segmented, glk-calendar) turn this off again: their first button is
+  // not the chosen one.
+  static get delegatesFocus() { return true; }
+
   constructor() {
     super();
     this._internals = this.attachInternals();
   }
 
+  attributeChangedCallback(name, oldValue, newValue) {
+    super.attributeChangedCallback(name, oldValue, newValue);
+    // required, min, pattern, type … all change what counts as valid.
+    if (this._initialized) this.syncValidity();
+  }
+
   get form() { return this._internals.form; }
   get validationMessage() { return this._internals.validationMessage; }
   get validity() { return this._internals.validity; }
+  get willValidate() { return this._internals.willValidate; }
 
   checkValidity() { return this._internals.checkValidity(); }
   reportValidity() { return this._internals.reportValidity(); }
@@ -266,9 +412,36 @@ export class GlkFormElement extends GlkElement {
 
   setFormValue(value) {
     this._internals.setFormValue(value);
+    this.syncValidity();
   }
 
   setValidity(flags, message, anchor) {
     this._internals.setValidity(flags, message, anchor);
   }
+
+  /**
+   * The native field whose constraint validation the host reports, or null.
+   * Subclasses built around one field return it.
+   */
+  get _validityField() { return null; }
+
+  /**
+   * A form asks the host — checkValidity(), reportValidity(), submitting — and
+   * the host knows nothing by itself, so the inner field's verdict is copied
+   * over after everything that can change it: a value (every setFormValue
+   * lands here), an attribute, a reset. The field is the anchor: the browser's
+   * bubble points at it, and reportValidity() focuses it.
+   */
+  syncValidity() {
+    const field = this._validityField;
+    if (!field) return;
+    const message = field.validationMessage;
+    // A field barred from validation (disabled) can still carry flags, but
+    // it has no message, and setValidity() refuses flags without one.
+    if (!field.willValidate || field.validity.valid || !message) {
+      this._internals.setValidity({});
+    } else {
+      this._internals.setValidity(field.validity, message, field);
+    }
+  }
 }

package/src/components/buttons/glk-button.js

@@ -1,11 +1,26 @@
-import { GlkElement } from '../../base.js';
+import { GlkElement, forwardHostClicks } from '../../base.js';
 
 const VARIANTS = ['primary', 'secondary', 'tertiary'];
 const SIZES = ['sm', 'md', 'lg', 'auto'];
 
+// States that whoever owns the element sets on it — <glk-popover> sets
+// aria-expanded on its trigger. Assistive technology reads the native button
+// inside, so they are handed down to it.
+const FORWARDED_ARIA = ['aria-expanded', 'aria-haspopup', 'aria-pressed'];
+
 class GlkButton extends GlkElement {
   static get observedAttributes() {
-    return ['variant', 'size', 'disabled', 'type'];
+    return ['variant', 'size', 'disabled', 'type', ...FORWARDED_ARIA];
+  }
+
+  // The native button sits in the shadow root, outside every form. Form
+  // association gives the element its form, so type="submit" and "reset"
+  // can act on it (see _activateForm).
+  static formAssociated = true;
+
+  constructor() {
+    super();
+    this._internals = this.attachInternals();
   }
 
   render() {
@@ -16,6 +31,7 @@ class GlkButton extends GlkElement {
     if (this.getBoolAttr('disabled')) {
       this._btn.disabled = true;
     }
+    for (const attr of FORWARDED_ARIA) this._forward(attr);
 
     this._btn.appendChild(document.createElement('slot'));
     this._wrapper.appendChild(this._btn);
@@ -29,12 +45,50 @@ class GlkButton extends GlkElement {
         return;
       }
       this.emit('glk-click');
+      this._activateForm(e);
     };
     this._btn.addEventListener('click', this._onClick);
+    // host.click() and a <label> for the element reach the host only.
+    this._unforwardClicks = forwardHostClicks(this, () => this._btn);
   }
 
   teardownEvents() {
     this._btn?.removeEventListener('click', this._onClick);
+    this._unforwardClicks?.();
+  }
+
+  /**
+   * type="submit" submits the element's form, type="reset" resets it. Both
+   * wait until the click has finished bubbling, so a listener that calls
+   * preventDefault() on the click stops them — as on a native button.
+   */
+  _activateForm(click) {
+    const type = this.getAttribute('type');
+    const form = this._internals.form;
+    if (!form || (type !== 'submit' && type !== 'reset')) return;
+    // Through the prototype: a control with id or name "reset" or
+    // "requestSubmit" in the form shadows the methods on the form itself.
+    const { reset, requestSubmit } = HTMLFormElement.prototype;
+    setTimeout(() => {
+      if (click.defaultPrevented || this._internals.form !== form) return;
+      if (type === 'reset') {
+        reset.call(form);
+        return;
+      }
+      // requestSubmit() accepts native buttons only as the submitter, so the
+      // submit event is told about this element instead. The listener goes
+      // again right away: a form that fails validation fires no submit event,
+      // and the next submit must not inherit this submitter.
+      const nameSubmitter = (e) => {
+        Object.defineProperty(e, 'submitter', { configurable: true, get: () => this });
+      };
+      form.addEventListener('submit', nameSubmitter, { capture: true });
+      try {
+        requestSubmit.call(form);
+      } finally {
+        form.removeEventListener('submit', nameSubmitter, { capture: true });
+      }
+    });
   }
 
   onAttributeChanged(name) {
@@ -50,9 +104,17 @@ class GlkButton extends GlkElement {
       case 'type':
         this._btn.setAttribute('type', this.getAttribute('type') || 'button');
         break;
+      default:
+        if (FORWARDED_ARIA.includes(name)) this._forward(name);
     }
   }
 
+  _forward(attr) {
+    const value = this.getAttribute(attr);
+    if (value === null) this._btn.removeAttribute(attr);
+    else this._btn.setAttribute(attr, value);
+  }
+
   _computeClasses() {
     const classes = ['glass-btn'];
     const variant = this.getAttribute('variant');
@@ -74,6 +136,11 @@ class GlkButton extends GlkElement {
 
   get disabled() { return this.getBoolAttr('disabled'); }
   set disabled(v) { this.setBoolAttr('disabled', v); }
+
+  get type() { return this.getAttribute('type') || 'button'; }
+  set type(v) { this.setAttribute('type', v); }
+
+  get form() { return this._internals.form; }
 }
 
 customElements.define('glk-button', GlkButton);

package/src/components/containers/glk-accordion-item.js

@@ -9,17 +9,19 @@ class GlkAccordionItem extends GlkElement {
 
   render() {
     this._item = this.createElement('div', ['glass-accordion__item']);
-    if (this.getBoolAttr('open')) this._item.classList.add('is-open');
 
-    // Trigger button
-    this._trigger = this.createElement('button', ['glass-accordion__trigger']);
+    // Trigger button — says whether its section is open, and which one it is
+    this._trigger = this.createElement('button', ['glass-accordion__trigger'], {
+      type: 'button',
+      'aria-controls': 'content'
+    });
     this.takeTitle();
     this._triggerText = document.createTextNode(this._title || '');
     this._trigger.appendChild(this._triggerText);
     this._trigger.insertAdjacentHTML('beforeend', CHEVRON_SVG);
 
     // Content
-    this._content = this.createElement('div', ['glass-accordion__content']);
+    this._content = this.createElement('div', ['glass-accordion__content'], { id: 'content' });
     const body = this.createElement('div', ['glass-accordion__body']);
     body.appendChild(document.createElement('slot'));
     this._content.appendChild(body);
@@ -28,6 +30,19 @@ class GlkAccordionItem extends GlkElement {
     this._item.appendChild(this._content);
 
     this._wrapper.appendChild(this._item);
+    this._applyOpen();
+  }
+
+  /**
+   * A closed section is only squeezed to zero height; its links and fields
+   * stayed in the tab order. inert takes them out, and out of the
+   * accessibility tree, until the section opens.
+   */
+  _applyOpen() {
+    const open = this.getBoolAttr('open');
+    this._item.classList.toggle('is-open', open);
+    this._trigger.setAttribute('aria-expanded', String(open));
+    this._content.inert = !open;
   }
 
   setupEvents() {
@@ -46,7 +61,7 @@ class GlkAccordionItem extends GlkElement {
     if (!this._item) return;
     switch (name) {
       case 'open':
-        this._item.classList.toggle('is-open', this.getBoolAttr('open'));
+        this._applyOpen();
         break;
       case 'title':
         if (this.takeTitle(value)) this._applyTitle();

package/src/components/feedback/glk-modal.js

@@ -1,5 +1,28 @@
 import { GlkElement } from '../../base.js';
 
+// Since 1.20.0 the overlay is a native <dialog>, opened with showModal(). The
+// browser then does what a modal needs: the dialog lies in the top layer, the
+// page behind it is inert — for the pointer, the keyboard and screen readers
+// alike — focus moves in on opening and goes back to where it came from on
+// closing, and the content is out of reach while the modal is closed.
+// GlassKit (1.20.0) styles dialog.glass-modal-overlay for this.
+//
+// The element keeps the fade: the dialog opens before .is-active is set and
+// closes only after the overlay has faded (safety net 400 ms; at once under
+// prefers-reduced-motion). Escape arrives as the dialog's cancel event and
+// takes the same path as a click on the dimmed area.
+//
+// Which element gets the focus on opening, the browsers decide differently:
+// Chrome takes the first field of the content, Safari the first action. An
+// element marked autofocus — in the content or among the actions — settles
+// it in both.
+
+const CLOSE_FALLBACK_MS = 400;
+
+function reducedMotion() {
+  return typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+
 class GlkModal extends GlkElement {
   static get observedAttributes() {
     return ['open', 'title'];
@@ -8,13 +31,13 @@ class GlkModal extends GlkElement {
   static get observesLightDom() { return true; }
 
   render() {
-    this._overlay = this.createElement('div', ['glass-modal-overlay'], { part: 'overlay' });
+    this._overlay = this.createElement('dialog', ['glass-modal-overlay'], { part: 'overlay' });
 
     const modal = this.createElement('div', ['glass-modal'], { part: 'modal' });
 
-    // Header
+    // Header — the title names the dialog
     const header = this.createElement('div', ['glass-modal__header'], { part: 'header' });
-    this._titleEl = this.createElement('h2', ['glass-modal__title']);
+    this._titleEl = this.createElement('h2', ['glass-modal__title'], { id: 'title' });
     this.takeTitle();
     this._applyTitle();
     header.appendChild(this._titleEl);
@@ -35,10 +58,8 @@ class GlkModal extends GlkElement {
 
     this._overlay.appendChild(modal);
     this._wrapper.appendChild(this._overlay);
-
-    if (this.getBoolAttr('open')) {
-      this._overlay.classList.add('is-active');
-    }
+    // `open` is applied in setupEvents, which also runs when a moved element
+    // comes back.
   }
 
   projectLightDom() {
@@ -63,33 +84,49 @@ class GlkModal extends GlkElement {
   setupEvents() {
     // Close on overlay click (outside modal)
     this._onOverlayClick = (e) => {
-      if (e.target === this._overlay) {
-        this.removeAttribute('open');
-        this.emit('glk-close');
-      }
+      if (e.target === this._overlay) this._dismiss();
     };
     this._overlay.addEventListener('click', this._onOverlayClick);
 
-    // Close on Escape
-    this._onKeydown = (e) => {
-      if (e.key === 'Escape' && this.getBoolAttr('open')) {
-        this.removeAttribute('open');
-        this.emit('glk-close');
-      }
+    // Escape: the dialog would close at once; it fades out like a click outside.
+    this._onCancel = (e) => {
+      e.preventDefault();
+      this._dismiss();
     };
-    document.addEventListener('keydown', this._onKeydown);
+    this._overlay.addEventListener('cancel', this._onCancel);
+
+    // The browser may also close the dialog by itself — Chrome does on a
+    // second Escape without user activation in between, skipping cancel.
+    this._onClose = () => {
+      if (this._overlay.open) return;       // a late event from an earlier close
+      this._overlay.classList.remove('is-active');
+      if (this.open) this._dismiss();
+    };
+    this._overlay.addEventListener('close', this._onClose);
+
+    if (this.open) this._show();
   }
 
   teardownEvents() {
     this._overlay?.removeEventListener('click', this._onOverlayClick);
-    document.removeEventListener('keydown', this._onKeydown);
+    this._overlay?.removeEventListener('cancel', this._onCancel);
+    this._overlay?.removeEventListener('close', this._onClose);
+    // Taken out of the document, the dialog leaves the top layer but stays
+    // open — shown in place, not modal. Closed now, it opens as a modal again
+    // when the element comes back.
+    clearTimeout(this._closeTimer);
+    this._overlay?.removeEventListener('transitionend', this._onFaded);
+    this._overlay?.classList.remove('is-active');
+    if (this._overlay?.open) this._overlay.close();
   }
 
   onAttributeChanged(name, _old, value) {
     if (!this._overlay) return;
     switch (name) {
       case 'open':
-        this._overlay.classList.toggle('is-active', this.getBoolAttr('open'));
+        if (!this.isConnected) return;      // setupEvents applies it on connect
+        if (this.open) this._show();
+        else this._hide();
         break;
       case 'title':
         if (this.takeTitle(value)) this._applyTitle();
@@ -97,11 +134,52 @@ class GlkModal extends GlkElement {
     }
   }
 
+  _show() {
+    const dialog = this._overlay;
+    clearTimeout(this._closeTimer);
+    dialog.removeEventListener('transitionend', this._onFaded);
+    if (!dialog.open) {
+      dialog.showModal();
+      // The actions are copies in the shadow root; the originals are not shown.
+      (this._footer.querySelector('[autofocus]') || this.querySelector('[autofocus]'))?.focus();
+    }
+    void dialog.offsetHeight; // reflow, so the fade starts from the closed state
+    requestAnimationFrame(() => {
+      if (this.open) dialog.classList.add('is-active');
+    });
+  }
+
+  _hide() {
+    const dialog = this._overlay;
+    dialog.classList.remove('is-active');
+    this._onFaded = (event) => {
+      if (event && event.target !== dialog) return;   // the panel's own transition
+      clearTimeout(this._closeTimer);
+      dialog.removeEventListener('transitionend', this._onFaded);
+      if (!this.open && dialog.open) dialog.close();
+    };
+    if (!dialog.open || reducedMotion()) {
+      this._onFaded();
+      return;
+    }
+    dialog.addEventListener('transitionend', this._onFaded);
+    this._closeTimer = setTimeout(this._onFaded, CLOSE_FALLBACK_MS);
+  }
+
+  /** Closed by the user — a click outside, Escape. */
+  _dismiss() {
+    this.removeAttribute('open');
+    this.emit('glk-close');
+  }
+
   show() { this.setAttribute('open', ''); }
   close() { this.removeAttribute('open'); }
 
   _applyTitle() {
-    if (this._titleEl) this._titleEl.textContent = this._title || '';
+    if (!this._titleEl) return;
+    this._titleEl.textContent = this._title || '';
+    if (this._title) this._overlay.setAttribute('aria-labelledby', 'title');
+    else this._overlay.removeAttribute('aria-labelledby');
   }
 
   // `title` is the heading, never a tooltip — see GlkElement.takeTitle().