@alacris/ui 0.4.0 → 0.4.2

package/README.md

@@ -46,10 +46,10 @@ The published package is plain ESM. Point an import map at a pinned CDN build of
 <script type="importmap">
 {
   "imports": {
-    "@alacris/core": "https://cdn.jsdelivr.net/npm/@alacris/core@0.11.3/dist/alacris.js",
-    "@alacris/ui": "https://cdn.jsdelivr.net/npm/@alacris/ui@0.4.0/src/index.js",
-    "@alacris/ui/theme": "https://cdn.jsdelivr.net/npm/@alacris/ui@0.4.0/src/theme/index.js",
-    "@alacris/ui/components/": "https://cdn.jsdelivr.net/npm/@alacris/ui@0.4.0/src/components/"
+    "@alacris/core": "https://cdn.jsdelivr.net/npm/@alacris/core@0.11.4/dist/alacris.js",
+    "@alacris/ui": "https://cdn.jsdelivr.net/npm/@alacris/ui@0.4.2/src/index.js",
+    "@alacris/ui/theme": "https://cdn.jsdelivr.net/npm/@alacris/ui@0.4.2/src/theme/index.js",
+    "@alacris/ui/components/": "https://cdn.jsdelivr.net/npm/@alacris/ui@0.4.2/src/components/"
   }
 }
 </script>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alacris/ui",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Themeable design system for Alacris — Material defaults, sixty-eight custom elements, ESM-only, no build step.",
   "type": "module",
   "exports": {

package/src/components/base.js

@@ -13,7 +13,7 @@ export const base = css`
     font-synthesis: none;
     -webkit-tap-highlight-color: transparent;
   }
-  :host([hidden]) { display: none; }
+  :host([hidden]) { display: none !important; }
   @media (prefers-reduced-motion: reduce) {
     *, *::before, *::after {
       transition-duration: 0.01ms;

package/src/components/ui-autocomplete.js

@@ -185,7 +185,7 @@ const styles = css`
 
   .panel {
     position: fixed;
-    z-index: ${sys.z.modal};
+    z-index: ${sys.z.popup};
     min-inline-size: 112px;
     max-block-size: 40vh;
     overflow: auto;
@@ -276,8 +276,16 @@ define('ui-autocomplete', {
       open.set(false);
     };
 
+    let isComposing = false;
+    const onCompositionStart = () => { isComposing = true; };
+    const onCompositionEnd = (e) => {
+      isComposing = false;
+      onInput(e);
+    };
+
     const onInput = (e) => {
       e.stopPropagation();
+      if (isComposing) return;
       query.set(e.target.value);
       open.set(true);
       host.emit('input', { value: e.target.value });
@@ -358,6 +366,8 @@ define('ui-autocomplete', {
                  .value=${query}
                  placeholder=${() => placeholder() || null}
                  ?disabled=${disabled} ?required=${required}
+                 @compositionstart=${onCompositionStart}
+                 @compositionend=${onCompositionEnd}
                  @input=${onInput} @change=${(e) => e.stopPropagation()} @keydown=${onKeydown}
                  @focus=${onFocus} @blur=${onBlur}>
           <ui-icon class="arrow" name="arrow-drop-down"></ui-icon>

package/src/components/ui-date-picker.js

@@ -26,8 +26,8 @@
 // @prop  {string}  placeholder=''
 // @event change — committed; detail: { value } or { start, end, value } when range
 // @event input  — field keystroke; detail: { value } (the raw text)
-// @event open   — calendar visible (after the enter animation)
-// @event close  — calendar removed (after the exit animation)
+// @event open   — calendar visible (after the enter animation); does not bubble
+// @event close  — calendar removed (after the exit animation); does not bubble
 // @part  field, input, label, panel, day
 // @vars  see `t` below (`themeVars.names`)
 
@@ -39,6 +39,7 @@ import { presence } from '../motion/presence.js';
 import { animate, fx } from '../motion/animate.js';
 import { autoUpdate } from '../util/position.js';
 import { escapeLayer } from '../util/keys.js';
+import { popupEvent } from '../util/popup.js';
 import { focusTrap, scrollLock } from '../util/focus.js';
 import './ui-icon-button.js';
 import './ui-button.js';
@@ -262,7 +263,7 @@ const styles = css`
 
   .panel {
     position: fixed;
-    z-index: ${sys.z.modal};
+    z-index: ${sys.z.popup};
     padding: ${sys.space(3)} ${sys.space(3)} ${sys.space(4)};
     background: ${t.panelBg};
     border-radius: ${t.panelRadius};
@@ -273,7 +274,7 @@ const styles = css`
   .overlay {
     position: fixed;
     inset: 0;
-    z-index: ${sys.z.modal};
+    z-index: ${sys.z.popup};
     display: grid;
     place-items: center;
   }
@@ -758,16 +759,16 @@ define('ui-date-picker', {
           exit: fx.scaleOut,
           enterDuration: 'short4',
           exitDuration: 'short4',
-          onEntered: () => host.emit('open'),
-          onExited: () => host.emit('close'),
+          onEntered: () => host.emit('open', null, popupEvent),
+          onExited: () => host.emit('close', null, popupEvent),
         })}
         ${presence(() => open() && presentation() === 'modal', modalView, {
           enter: fx.fadeIn,
           exit: fx.fadeOut,
           enterDuration: 'medium2',
           exitDuration: 'short4',
-          onEntered: () => host.emit('open'),
-          onExited: () => host.emit('close'),
+          onEntered: () => host.emit('open', null, popupEvent),
+          onExited: () => host.emit('close', null, popupEvent),
         })}
       </div>`;
   },

package/src/components/ui-dialog.js

@@ -111,19 +111,22 @@ define('ui-dialog', {
     };
 
     // Trap focus + lock scroll exactly while open; presence handles the DOM.
+    let prevActive = null;
     effect(() => {
       if (open()) {
+        prevActive = document.activeElement;
         document.addEventListener('keydown', onDocKeydown, true);
         unlock = scrollLock();
         // The surface renders synchronously with the signal write, but wait a
         // microtask so slotted content is distributed before we look for it.
         queueMicrotask(() => {
-          if (open() && !releaseTrap) releaseTrap = focusTrap(host);
+          if (open() && !releaseTrap) releaseTrap = focusTrap(host, { restore: prevActive });
         });
       } else {
         document.removeEventListener('keydown', onDocKeydown, true);
         releaseTrap?.();
         releaseTrap = null;
+        prevActive = null;
         unlock?.();
         unlock = null;
         if (surfaceEl?.isConnected) {

package/src/components/ui-drawer.js

@@ -26,7 +26,7 @@ import { define, html, css, vars, effect, onCleanup } from '@alacris/core';
 import { sys } from '../tokens/sys.js';
 import { base } from './base.js';
 import { presence } from '../motion/presence.js';
-import { animate, fx } from '../motion/animate.js';
+import { animate, fx, releaseFill } from '../motion/animate.js';
 import { focusTrap, scrollLock } from '../util/focus.js';
 
 const t = vars('ui-drawer', {
@@ -105,17 +105,20 @@ define('ui-drawer', {
     };
 
     // Trap focus + lock scroll exactly while the modal drawer is open.
+    let prevActive = null;
     effect(() => {
       if (open() && variant() === 'modal') {
+        prevActive = document.activeElement;
         document.addEventListener('keydown', onDocKeydown, true);
         if (!unlock) unlock = scrollLock();
         queueMicrotask(() => {
-          if (open.peek() && !releaseTrap) releaseTrap = focusTrap(host);
+          if (open.peek() && !releaseTrap) releaseTrap = focusTrap(host, { restore: prevActive });
         });
       } else {
         document.removeEventListener('keydown', onDocKeydown, true);
         releaseTrap?.();
         releaseTrap = null;
+        prevActive = null;
         unlock?.();
         unlock = null;
       }
@@ -135,7 +138,7 @@ define('ui-drawer', {
 
     const surfaceRef = (el) => {
       surfaceEl = el;
-      animate(el, slideIn(), { duration: 'medium2', easing: 'emphasizedDecelerate' });
+      releaseFill(animate(el, slideIn(), { duration: 'medium2', easing: 'emphasizedDecelerate' }));
     };
 
     const overlay = () => html`

package/src/components/ui-fab-menu.js

@@ -14,8 +14,8 @@
 //
 // @prop  {boolean} open=false
 // @prop  {string}  label='' — accessible name for the action list
-// @event open  — menu visible (after the enter animation)
-// @event close — menu removed (after the exit animation)
+// @event open  — menu visible (after the enter animation); does not bubble
+// @event close — menu removed (after the exit animation); does not bubble
 // @slot  trigger  — the <ui-fab> that toggles the menu
 // @slot  (default) — related <ui-fab> actions
 // @part  actions, trigger
@@ -26,6 +26,7 @@ import { sys } from '../tokens/sys.js';
 import { base } from './base.js';
 import { presence } from '../motion/presence.js';
 import { fx } from '../motion/animate.js';
+import { popupEvent } from '../util/popup.js';
 import './ui-fab.js';
 
 const t = vars('ui-fab-menu', {
@@ -112,8 +113,8 @@ define('ui-fab-menu', {
         exit: fx.scaleOut,
         enterDuration: 'short4',
         exitDuration: 'short2',
-        onEntered: () => host.emit('open'),
-        onExited: () => host.emit('close'),
+        onEntered: () => host.emit('open', null, popupEvent),
+        onExited: () => host.emit('close', null, popupEvent),
       })}`;
   },
 });

package/src/components/ui-menu.js

@@ -16,8 +16,8 @@
 // @prop  {boolean} open=false
 // @prop  {string}  placement='bottom-start' — side[-alignment] (see util/position.js)
 // @event select — an item was chosen; detail: { value }
-// @event open   — panel visible (after the enter animation)
-// @event close  — panel removed (after the exit animation)
+// @event open   — panel visible (after the enter animation); does not bubble
+// @event close  — panel removed (after the exit animation); does not bubble
 // @slot  anchor    — the trigger element
 // @slot  (default) — <ui-menu-item> children
 // @part  panel — the floating menu surface
@@ -30,6 +30,7 @@ import { presence } from '../motion/presence.js';
 import { fx } from '../motion/animate.js';
 import { autoUpdate } from '../util/position.js';
 import { rovingTabindex } from '../util/keys.js';
+import { popupEvent } from '../util/popup.js';
 import './ui-menu-item.js';
 
 const t = vars('ui-menu', {
@@ -47,7 +48,7 @@ const styles = css`
     position: fixed;
     inset-inline-start: 0;
     inset-block-start: 0;
-    z-index: ${sys.z.modal};
+    z-index: ${sys.z.popup};
     min-inline-size: ${t.minWidth};
     max-inline-size: ${t.maxWidth};
     padding-block: ${sys.space(2)};
@@ -182,8 +183,8 @@ define('ui-menu', {
         exitDuration: 'short2',
         enterEasing: 'emphasizedDecelerate',
         exitEasing: 'emphasizedAccelerate',
-        onEntered: () => host.emit('open'),
-        onExited: () => host.emit('close'),
+        onEntered: () => host.emit('open', null, popupEvent),
+        onExited: () => host.emit('close', null, popupEvent),
       })}`;
   },
 });

package/src/components/ui-search.js

@@ -28,8 +28,8 @@
 // @event change — committed (blur/Enter); detail: { value }
 // @event submit — Enter pressed; detail: { value }
 // @event clear  — the clear affordance was used
-// @event open   — suggestions visible (after the enter animation)
-// @event close  — suggestions removed (after the exit animation)
+// @event open   — suggestions visible (after the enter animation); does not bubble
+// @event close  — suggestions removed (after the exit animation); does not bubble
 // @slot  leading  — replaces the search icon
 // @slot  trailing — after the clear button (avatar, extra actions)
 // @slot  (default) — suggestion rows (ui-list-item, …). The panel is a list
@@ -43,6 +43,7 @@ import { base } from './base.js';
 import { formBind } from '../util/form.js';
 import { presence } from '../motion/presence.js';
 import { fx } from '../motion/animate.js';
+import { popupEvent } from '../util/popup.js';
 import './ui-icon.js';
 import './ui-icon-button.js';
 
@@ -75,7 +76,7 @@ const styles = css`
   }
   .shell.open {
     overflow: visible;
-    z-index: ${sys.z.modal};
+    z-index: ${sys.z.popup};
     background: ${t.panelBg};
     border-start-start-radius: ${t.panelRadius};
     border-start-end-radius: ${t.panelRadius};
@@ -307,8 +308,8 @@ define('ui-search', {
           enterEasing: 'emphasizedDecelerate',
           exitDuration: 'short4',
           exitEasing: 'emphasizedAccelerate',
-          onEntered: () => host.emit('open'),
-          onExited: () => host.emit('close'),
+          onEntered: () => host.emit('open', null, popupEvent),
+          onExited: () => host.emit('close', null, popupEvent),
         })}
       </div>`;
   },

package/src/components/ui-select.js

@@ -10,7 +10,9 @@
 // arrows move the active option, Enter/Space selects it, Escape closes the
 // panel only — an enclosing dialog keeps its own Escape for a second press,
 // typing jumps to the next option starting with that letter. The panel closes
-// on outside pointerdown and returns focus to the field.
+// on outside pointerdown and returns focus to the field. `open`/`close` do
+// not bubble: they share those names with dialogs and sheets, and a bubbling
+// select-close looks like the sheet dismissed itself.
 //
 // Past a handful of options the panel gets a filter field, because scrolling
 // is not a way to find one entry among several hundred. It takes focus when
@@ -31,8 +33,8 @@
 // @prop  {number}  searchThreshold=8
 // @prop  {string}  searchPlaceholder='Search'
 // @event change — an option was chosen; detail: { value }
-// @event open   — panel enter animation finished
-// @event close  — panel exit animation finished
+// @event open   — panel enter animation finished; does not bubble
+// @event close  — panel exit animation finished; does not bubble
 // @slot  (default) — <ui-option> children (projected into the panel)
 // @part  control — the field button (role="combobox")
 // @part  label, panel
@@ -50,6 +52,7 @@ import { presence } from '../motion/presence.js';
 import { fx } from '../motion/animate.js';
 import { autoUpdate } from '../util/position.js';
 import { escapeLayer } from '../util/keys.js';
+import { popupEvent } from '../util/popup.js';
 import './ui-icon.js';
 import './ui-option.js';
 
@@ -210,7 +213,7 @@ const styles = css`
 
   .panel {
     position: fixed;
-    z-index: ${sys.z.modal};
+    z-index: ${sys.z.popup};
     min-inline-size: 112px;
     max-block-size: 40vh;
     /* The filter field stays put while the options scroll under it, so the
@@ -553,8 +556,8 @@ define('ui-select', {
           exitDuration: 'short2',
           enterEasing: 'emphasizedDecelerate',
           exitEasing: 'emphasizedAccelerate',
-          onEntered: () => host.emit('open'),
-          onExited: () => host.emit('close'),
+          onEntered: () => host.emit('open', null, popupEvent),
+          onExited: () => host.emit('close', null, popupEvent),
         })}
       </div>`;
   },

package/src/components/ui-sheet.js

@@ -29,7 +29,7 @@ import { define, html, css, vars, effect, onCleanup, signal } from '@alacris/cor
 import { sys } from '../tokens/sys.js';
 import { base } from './base.js';
 import { presence } from '../motion/presence.js';
-import { animate, fx } from '../motion/animate.js';
+import { animate, fx, releaseFill } from '../motion/animate.js';
 import { focusTrap, scrollLock } from '../util/focus.js';
 
 const t = vars('ui-sheet', {
@@ -126,17 +126,20 @@ define('ui-sheet', {
       if (e.key === 'Escape') requestClose('esc');
     };
 
+    let prevActive = null;
     effect(() => {
       if (open() && variant() !== 'standard') {
+        prevActive = document.activeElement;
         document.addEventListener('keydown', onDocKeydown, true);
         unlock = scrollLock();
         queueMicrotask(() => {
-          if (open() && !releaseTrap) releaseTrap = focusTrap(host);
+          if (open() && !releaseTrap) releaseTrap = focusTrap(host, { restore: prevActive });
         });
       } else {
         document.removeEventListener('keydown', onDocKeydown, true);
         releaseTrap?.();
         releaseTrap = null;
+        prevActive = null;
         unlock?.();
         unlock = null;
         if (surfaceEl?.isConnected) {
@@ -163,7 +166,7 @@ define('ui-sheet', {
              aria-labelledby=${() => (hasHeadline() ? 'headline' : null)}
              aria-label=${() => (hasHeadline() ? null : (label() || 'Sheet'))}
              tabindex="-1"
-             ref=${(el) => { surfaceEl = el; animate(el, fx.sheetIn, { duration: 'medium2', easing: 'emphasizedDecelerate' }); }}>
+             ref=${(el) => { surfaceEl = el; releaseFill(animate(el, fx.sheetIn, { duration: 'medium2', easing: 'emphasizedDecelerate' })); }}>
           <div class="handle" part="handle" aria-hidden="true"></div>
           <div class="headline" part="headline" id="headline"
                ref=${(el) => hasSlot(el.querySelector('slot'), (has) => {

package/src/components/ui-side-sheet.js

@@ -29,7 +29,7 @@ import { define, html, css, vars, effect, onCleanup, signal } from '@alacris/cor
 import { sys } from '../tokens/sys.js';
 import { base } from './base.js';
 import { presence } from '../motion/presence.js';
-import { animate, fx } from '../motion/animate.js';
+import { animate, fx, releaseFill } from '../motion/animate.js';
 import { focusTrap, scrollLock } from '../util/focus.js';
 import './ui-icon-button.js';
 
@@ -130,17 +130,20 @@ define('ui-side-sheet', {
       if (e.key === 'Escape') requestClose('esc');
     };
 
+    let prevActive = null;
     effect(() => {
       if (open() && variant() !== 'standard') {
+        prevActive = document.activeElement;
         document.addEventListener('keydown', onDocKeydown, true);
         unlock = scrollLock();
         queueMicrotask(() => {
-          if (open() && !releaseTrap) releaseTrap = focusTrap(host);
+          if (open() && !releaseTrap) releaseTrap = focusTrap(host, { restore: prevActive });
         });
       } else {
         document.removeEventListener('keydown', onDocKeydown, true);
         releaseTrap?.();
         releaseTrap = null;
+        prevActive = null;
         unlock?.();
         unlock = null;
       }
@@ -158,7 +161,7 @@ define('ui-side-sheet', {
 
     const surfaceRef = (el) => {
       surfaceEl = el;
-      animate(el, slideIn(), { duration: 'medium2', easing: 'emphasizedDecelerate' });
+      releaseFill(animate(el, slideIn(), { duration: 'medium2', easing: 'emphasizedDecelerate' }));
     };
 
     const hasSlot = (el, set) => {

package/src/components/ui-switch.js

@@ -144,7 +144,7 @@ define('ui-switch', {
             ${() => (icons() ? html`<ui-icon name=${() => (checked() ? 'check' : 'close')}></ui-icon>` : null)}
           </span>
         </button>
-        ${() => (label() ? html`<span id="label">${label}</span>` : null)}
+        ${() => (label() ? html`<span id="label" part="label">${label}</span>` : html`<slot></slot>`)}
       </label>`;
   },
 });

package/src/components/ui-text-field.js

@@ -320,7 +320,15 @@ define('ui-text-field', {
        hasLeading() && 'with-leading', type() === 'textarea' && 'multiline',
        type() === 'number' && 'numeric'].filter(Boolean).join(' '));
 
+    let isComposing = false;
+    const onCompositionStart = () => { isComposing = true; };
+    const onCompositionEnd = (e) => {
+      isComposing = false;
+      onInput(e);
+    };
+
     const onInput = (e) => {
+      if (isComposing) return;
       value.set(e.target.value);
       host.emit('input', { value: value() });
     };
@@ -350,6 +358,8 @@ define('ui-text-field', {
               spellcheck=${attr(spellcheck)}
               inputmode=${attr(inputmode)}
               enterkeyhint=${attr(enterkeyhint)}
+              @compositionstart=${onCompositionStart}
+              @compositionend=${onCompositionEnd}
               @input=${onInput} @change=${commit}
               @focus=${() => focused.set(true)} @blur=${() => focused.set(false)}></textarea></span>`
         : html`<input part="input" ref=${(el) => (input = el)}
@@ -364,6 +374,8 @@ define('ui-text-field', {
               spellcheck=${attr(spellcheck)}
               inputmode=${attr(inputmode)}
               enterkeyhint=${attr(enterkeyhint)}
+              @compositionstart=${onCompositionStart}
+              @compositionend=${onCompositionEnd}
               @input=${onInput} @change=${commit}
               @focus=${() => focused.set(true)} @blur=${() => focused.set(false)}>`)}
       ${() => (clearable() && value() !== '' && !disabled()

package/src/components/ui-time-picker.js

@@ -21,8 +21,8 @@
 // @prop  {string}  placeholder=''
 // @event change — committed; detail: { value }
 // @event input  — field keystroke; detail: { value } (the raw text)
-// @event open   — panel visible (after the enter animation)
-// @event close  — panel removed (after the exit animation)
+// @event open   — panel visible (after the enter animation); does not bubble
+// @event close  — panel removed (after the exit animation); does not bubble
 // @part  field, input, label, panel, dial
 // @vars  see `t` below (`themeVars.names`)
 
@@ -34,6 +34,7 @@ import { presence } from '../motion/presence.js';
 import { fx } from '../motion/animate.js';
 import { autoUpdate } from '../util/position.js';
 import { rovingTabindex } from '../util/keys.js';
+import { popupEvent } from '../util/popup.js';
 import './ui-icon-button.js';
 
 const TIME = /^(\d{1,2}):(\d{2})$/;
@@ -215,7 +216,7 @@ const styles = css`
 
   .panel {
     position: fixed;
-    z-index: ${sys.z.modal};
+    z-index: ${sys.z.popup};
     display: flex;
     flex-direction: column;
     gap: ${sys.space(3)};
@@ -742,8 +743,8 @@ define('ui-time-picker', {
           exit: fx.scaleOut,
           enterDuration: 'short4',
           exitDuration: 'short4',
-          onEntered: () => host.emit('open'),
-          onExited: () => host.emit('close'),
+          onEntered: () => host.emit('open', null, popupEvent),
+          onExited: () => host.emit('close', null, popupEvent),
         })}
       </div>`;
   },

package/src/index.js

@@ -20,7 +20,7 @@ export {
 } from './tokens/typography.js';
 
 // Motion
-export { animate, settled, duration, easing, fx, prefersReducedMotion } from './motion/animate.js';
+export { animate, releaseFill, settled, duration, easing, fx, prefersReducedMotion } from './motion/animate.js';
 export { presence } from './motion/presence.js';
 export { withFlip } from './motion/flip.js';
 export { ripple } from './motion/ripple.js';

package/src/motion/animate.js

@@ -104,6 +104,20 @@ export function animate(el, keyframes, opts = {}) {
 /** Await an animation without throwing when it is cancelled mid-flight. */
 export const settled = (anim) => anim.finished.catch(() => {});
 
+/**
+ * Drop fill:both once an enter animation has settled.
+ *
+ * A leftover transform is a containing block for `position:fixed`
+ * descendants — a select inside a side sheet is then placed in viewport
+ * pixels against the surface, so the list sits beside the sheet, under
+ * it, or clipped by the body's overflow. presence() already releases
+ * the overlay fade; surfaces animated directly need the same.
+ */
+export function releaseFill(anim) {
+  anim.finished.then(() => { try { anim.cancel(); } catch { /* already cancelled */ } });
+  return anim;
+}
+
 // ------------------------------------------------------------------ presets
 //
 // Keyframe presets tuned to the Material motion spec. Enter presets pair with

package/src/motion/index.js

@@ -1,4 +1,4 @@
-export { animate, settled, duration, easing, fx, prefersReducedMotion } from './animate.js';
+export { animate, releaseFill, settled, duration, easing, fx, prefersReducedMotion } from './animate.js';
 export { presence } from './presence.js';
 export { withFlip } from './flip.js';
 export { ripple } from './ripple.js';

package/src/tokens/sys.js

@@ -65,6 +65,7 @@ export const sys = {
     appBar: v('z-app-bar'),
     drawer: v('z-drawer'),
     modal: v('z-modal'),
+    popup: v('z-popup'),
     snackbar: v('z-snackbar'),
     tooltip: v('z-tooltip'),
   },

package/src/tokens/system.js

@@ -103,6 +103,7 @@ export function zTokens() {
     'z-app-bar': '1100',
     'z-drawer': '1200',
     'z-modal': '1300',
+    'z-popup': '1350',
     'z-snackbar': '1400',
     'z-tooltip': '1500',
   };

package/src/util/focus.js

@@ -32,8 +32,8 @@ export function focusables(host) {
  *
  *   const release = focusTrap(host, { initial: shadowCloseButton });
  */
-export function focusTrap(host, { initial } = {}) {
-  const previous = document.activeElement;
+export function focusTrap(host, { initial, restore } = {}) {
+  const previous = restore || document.activeElement;
 
   const first = initial || focusables(host)[0] || host;
   first.focus?.();

package/src/util/popup.js

@@ -0,0 +1,5 @@
+// Popup lifecycle events share names with dialogs and sheets (`open` /
+// `close`). They must not bubble: choosing a select option would otherwise
+// look like the sheet dismissed itself. Listeners on the popup host still
+// fire — emit dispatches on the host regardless of bubbles.
+export const popupEvent = { bubbles: false };

package/types/index.d.ts

@@ -84,6 +84,7 @@ export interface AnimateOptions extends KeyframeAnimationOptions {
 }
 
 export function animate(el: Element, keyframes: Keyframes, opts?: AnimateOptions): Pick<Animation, 'finished' | 'cancel' | 'finish' | 'play' | 'pause'>;
+export function releaseFill<T extends { finished: Promise<unknown>; cancel(): void }>(anim: T): T;
 export function settled(anim: { finished: Promise<unknown> }): Promise<void>;
 export function duration(key: number | string): number;
 export function easing(key: string): string;