@leavepulse/ui 0.40.1 → 0.42.0

package/src/components/LpCommandPalette.vue

@@ -40,6 +40,7 @@ import { computed, nextTick, ref, shallowRef, useId, watch } from "vue"
 import LpIcon from "./LpIcon.vue"
 import LpScrollArea from "./LpScrollArea.vue"
 import { useAsyncTask } from "../composables/useAsyncTask"
+import { useGlass } from "../composables/useGlass"
 import { useClipboard } from "../composables/useClipboard"
 import { useHotkeys } from "../composables/useHotkeys"
 
@@ -210,7 +211,8 @@ const props = withDefaults(
     /**
      * Frosted glass instead of a solid panel: the page shows through,
      * blurred, under a lighter scrim (.lp-glass-overlay, .lp-scrim--light).
-     * A look, not a behaviour, so it is the app's call and off by default.
+     * A look, not a behaviour, so it is the app's call: unset follows
+     * `provideGlass`, and without one it is off.
      */
     glass?: boolean
   }>(),
@@ -227,10 +229,12 @@ const props = withDefaults(
     groupLimit: 0,
     layoutFallback: true,
     previewPane: false,
-    glass: false,
+    glass: undefined,
   },
 )
 
+const frosted = useGlass(() => props.glass)
+
 const DEFAULT_LABELS: PaletteLabels = {
   navigate: "navigate",
   select: "select",
@@ -272,6 +276,7 @@ function optionId(index: number): string {
 }
 const activeId = computed(() => (flat.value.length ? optionId(selectedIndex.value) : undefined))
 const selectedIndex = ref(0)
+const selectedId = ref<string | null>(null)
 const inputRef = ref<HTMLInputElement | null>(null)
 const scrollRef = ref<{ viewportEl: HTMLElement | null } | null>(null)
 
@@ -286,6 +291,7 @@ const scrollRef = ref<{ viewportEl: HTMLElement | null } | null>(null)
  * a row of data), and deep-tracking them would walk it on every keystroke.
  */
 const trail = shallowRef<Command[]>([])
+const trailState = shallowRef<{ query: string; selectedId: string | null }[]>([])
 const mode = computed<Command | null>(() => trail.value[trail.value.length - 1] ?? null)
 
 /*
@@ -328,21 +334,20 @@ const selectedActions = computed(() => actionsOf(flat.value[selectedIndex.value]
  * actions it keeps that default.
  */
 function onTab(event: KeyboardEvent) {
+  event.preventDefault()
+  event.stopPropagation()
   if (event.shiftKey) return
   const c = flat.value[selectedIndex.value]
   const actions = selectedActions.value
   if (!c || !actions.length) return
-  // The dialog's focus trap handles Tab too, and would hand focus to the
-  // mode chip this is about to render.
-  event.preventDefault()
-  event.stopPropagation()
   enter({ id: `${c.id}:actions`, label: c.label, icon: c.icon, children: actions })
 }
 
 function enter(c: Command) {
+  trailState.value = [...trailState.value, { query: query.value, selectedId: selectedId.value }]
   trail.value = [...trail.value, c]
   query.value = ""
-  selectedIndex.value = 0
+  select(0)
   modeItems.value = Array.isArray(c.children) ? c.children : []
   refresh()
   // Entering by click leaves the focus on the button that no longer exists,
@@ -353,13 +358,19 @@ function enter(c: Command) {
 
 /** Unwind the trail to `depth` entries — 0 is the root. */
 function popTo(depth: number) {
+  const state = trailState.value[depth] || { query: "", selectedId: null }
   const next = trail.value.slice(0, Math.max(0, depth))
+  trailState.value = trailState.value.slice(0, Math.max(0, depth))
   trail.value = next
-  query.value = ""
-  selectedIndex.value = 0
   const parent = next[next.length - 1]
   modeItems.value = parent && Array.isArray(parent.children) ? parent.children : []
+  query.value = state.query
+  select(0)
   refresh()
+  void nextTick(() => {
+    const index = state.selectedId ? flat.value.findIndex((c) => c.id === state.selectedId) : -1
+    select(index >= 0 ? index : 0)
+  })
   inputRef.value?.focus()
 }
 
@@ -483,12 +494,43 @@ function nearWord(term: string, label: string): boolean {
  * the same weights the palette always had; a typo match ranks below all of
  * them, so an exact hit is never outranked by a near one.
  */
-function score(c: Command, terms: string[]): number {
+interface SearchTerms {
+  include: string[]
+  exclude: string[]
+  groups: string[]
+}
+
+const QUERY_TOKEN = /(-?)(?:(in):)?(?:"([^"]*)"|(\S+))/giu
+
+function searchTerms(value: string): SearchTerms {
+  const out: SearchTerms = { include: [], exclude: [], groups: [] }
+  QUERY_TOKEN.lastIndex = 0
+  for (let match; (match = QUERY_TOKEN.exec(value)); ) {
+    const text = (match[3] ?? match[4] ?? "").trim().toLowerCase()
+    if (!text) continue
+    if (match[2] && !match[1]) out.groups.push(text)
+    else if (match[1]) out.exclude.push(text)
+    else out.include.push(text)
+  }
+  return out
+}
+
+function matches(c: Command, term: string): boolean {
+  return (
+    c.label.toLowerCase().includes(term) ||
+    (c.keywords ?? []).some((keyword) => keyword.toLowerCase().includes(term)) ||
+    (c.description?.toLowerCase().includes(term) ?? false)
+  )
+}
+
+function score(c: Command, terms: SearchTerms): number {
   const label = c.label.toLowerCase()
   const keywords = (c.keywords ?? []).map((k) => k.toLowerCase())
   const description = c.description?.toLowerCase() ?? ""
-  let total = 0
-  for (const term of terms) {
+  const group = c.group?.toLowerCase() ?? ""
+  if (terms.exclude.some((term) => matches(c, term)) || terms.groups.some((term) => !group.includes(term))) return 0
+  let total = terms.include.length ? 0 : 1
+  for (const term of terms.include) {
     let hit =
       (label.includes(term) ? 4 : 0) +
       (keywords.some((k) => k.includes(term)) ? 3 : 0) +
@@ -500,7 +542,7 @@ function score(c: Command, terms: string[]): number {
   return total
 }
 
-function rank(items: Command[], terms: string[]): Command[] {
+function rank(items: Command[], terms: SearchTerms): Command[] {
   return items
     .map((c) => ({ c, score: score(c, terms) }))
     .filter((e) => e.score > 0)
@@ -508,22 +550,27 @@ function rank(items: Command[], terms: string[]): Command[] {
     .map((e) => e.c)
 }
 
-const typedTerms = computed(() => query.value.trim().toLowerCase().split(/\s+/).filter(Boolean))
-
 /*
  * The local match and the terms it matched with — the swapped ones when the
  * layout fallback is what found it, so the highlight marks what actually hit.
  */
 const local = computed<{ items: Command[]; terms: string[] }>(() => {
-  const terms = typedTerms.value
+  const terms = searchTerms(query.value)
+  const filtered = query.value.trim()
+    ? source.value
+    : source.value.filter((c) => !c.hidden)
   // Empty query: show everything EXCEPT hidden commands (they only surface once
   // typed). With a query, hidden commands rank like any other.
-  if (!terms.length) return { items: source.value.filter((c) => !c.hidden), terms }
-  const items = rank(source.value, terms)
-  if (items.length || !props.layoutFallback) return { items, terms }
-  const swapped = terms.map(swapLayout)
-  const other = rank(source.value, swapped)
-  return other.length ? { items: other, terms: swapped } : { items, terms }
+  if (!terms.include.length && !terms.exclude.length && !terms.groups.length) return { items: filtered, terms: [] }
+  const items = rank(filtered, terms)
+  if (items.length || !props.layoutFallback) return { items, terms: terms.include }
+  const swapped: SearchTerms = {
+    include: terms.include.map(swapLayout),
+    exclude: terms.exclude.map(swapLayout),
+    groups: terms.groups.map(swapLayout),
+  }
+  const other = rank(filtered, swapped)
+  return other.length ? { items: other, terms: swapped.include } : { items, terms: terms.include }
 })
 
 const ranked = computed<Command[]>(() => local.value.items)
@@ -702,16 +749,17 @@ function highlight(value: string, extra: string[] = []): Part[] {
 
 // ── selection + keyboard ─────────────────────────────────────
 watch(query, () => {
-  selectedIndex.value = 0
+  select(0)
   refresh()
 })
 watch([query, trail, () => props.open], () => {
   expanded.value = new Set()
 })
 watch(
-  () => flat.value.length,
-  (len) => {
-    if (selectedIndex.value >= len) selectedIndex.value = Math.max(0, len - 1)
+  () => flat.value.map((c) => c.id).join("|"),
+  () => {
+    const index = selectedId.value ? flat.value.findIndex((c) => c.id === selectedId.value) : -1
+    select(index >= 0 ? index : 0)
   },
 )
 watch([selectedIndex, () => flat.value.map((c) => c.id).join("|")], async () => {
@@ -726,13 +774,42 @@ function scrollSelectedIntoView() {
   el?.scrollIntoView({ block: "nearest" })
 }
 
+const keyboardSelection = ref(false)
+
+function select(index: number, keyboard = false) {
+  const len = flat.value.length
+  selectedIndex.value = len ? Math.max(0, Math.min(index, len - 1)) : 0
+  selectedId.value = flat.value[selectedIndex.value]?.id ?? null
+  if (keyboard) keyboardSelection.value = true
+}
+
 function moveDown() {
   const len = flat.value.length
-  if (len) selectedIndex.value = (selectedIndex.value + 1) % len
+  if (len) select((selectedIndex.value + 1) % len, true)
 }
 function moveUp() {
   const len = flat.value.length
-  if (len) selectedIndex.value = (selectedIndex.value - 1 + len) % len
+  if (len) select((selectedIndex.value - 1 + len) % len, true)
+}
+function movePage(direction: -1 | 1) {
+  select(selectedIndex.value + direction * 8, true)
+}
+function onPaletteKeydown(event: KeyboardEvent) {
+  if (event.isComposing) return
+  if (!(["ArrowDown", "ArrowUp", "Home", "End", "PageDown", "PageUp"] as string[]).includes(event.key)) return
+  event.preventDefault()
+  event.stopPropagation()
+  if (event.key === "ArrowDown") moveDown()
+  else if (event.key === "ArrowUp") moveUp()
+  else if (event.key === "Home") select(0, true)
+  else if (event.key === "End") select(flat.value.length - 1, true)
+  else movePage(event.key === "PageDown" ? 1 : -1)
+}
+function onPointerMove() {
+  keyboardSelection.value = false
+}
+function onPointerEnter(c: Command) {
+  if (!keyboardSelection.value) select(flatIndexOf(c))
 }
 function runSelected(event?: KeyboardEvent) {
   const c = flat.value[selectedIndex.value]
@@ -785,7 +862,7 @@ function run(c: Command | undefined) {
     // Back to the top of a fresh list: the query that found this command is
     // spent, and leaving it would hide whatever the action just changed.
     query.value = ""
-    selectedIndex.value = 0
+    select(0)
     inputRef.value?.focus()
     return
   }
@@ -829,8 +906,10 @@ watch(
   async (o) => {
     cancel()
     query.value = ""
-    selectedIndex.value = 0
+    select(0)
+    selectedId.value = null
     trail.value = []
+    trailState.value = []
     modeItems.value = []
     found.value = []
     failed.value = false
@@ -864,14 +943,15 @@ useHotkeys(() =>
   <DialogRoot :open="open" @update:open="(v) => emit('update:open', v)">
     <DialogPortal>
       <DialogOverlay
-        :class="{ 'lp-scrim--light': glass }"
+        :class="{ 'lp-scrim--light': frosted }"
         class="lp-scrim fixed inset-0 z-(--z-overlay) data-[state=open]:animate-[fade-in_150ms_ease] data-[state=closed]:animate-[fade-out_130ms_ease]"
       />
       <DialogContent
         class="lp-cmd-dialog fixed left-1/2 top-[12vh] z-(--z-modal) flex max-h-[76vh] -translate-x-1/2 flex-col overflow-hidden rounded-card border border-line shadow-panel outline-none data-[state=open]:animate-[pop-in_160ms_var(--ease-emphasized)] data-[state=closed]:animate-[pop-out_130ms_ease]"
-        :class="[glass ? 'lp-glass-overlay' : 'bg-surface-raised', previewPane && 'lp-cmd-split']"
+        :class="[frosted ? 'lp-glass-overlay' : 'bg-surface-raised', previewPane && 'lp-cmd-split']"
         :data-pane="paneOpen ? 'open' : undefined"
         @open-auto-focus.prevent
+        @keydown.capture="onPaletteKeydown"
       >
         <DialogTitle class="sr-only">Command palette</DialogTitle>
         <DialogDescription class="sr-only">Search and run a command.</DialogDescription>
@@ -912,8 +992,6 @@ useHotkeys(() =>
             :aria-activedescendant="activeId"
             :placeholder="mode?.childPlaceholder ?? placeholder"
             class="h-12 min-w-0 flex-1 bg-transparent text-sm text-ink outline-none placeholder:text-muted"
-            @keydown.down.prevent="moveDown"
-            @keydown.up.prevent="moveUp"
             @keydown.enter.prevent="runSelected"
             @keydown.backspace="onBackspace"
             @keydown.esc="onEscape"
@@ -923,7 +1001,7 @@ useHotkeys(() =>
         </div>
 
         <!-- Results -->
-        <div class="flex min-h-0 flex-1">
+        <div class="flex min-h-0 flex-1" @pointermove="onPointerMove">
           <LpScrollArea ref="scrollRef" class="lp-cmd-list min-h-0 min-w-0 flex-1" content-class="p-2">
             <!-- While a request is out there is nothing to say yet: "no results"
                  under a spinner reads as an answer, and it is not one. -->
@@ -970,7 +1048,7 @@ useHotkeys(() =>
                         : 'text-ink hover:bg-surface-soft/60',
                   ]"
                   @click="onRowClick($event, c)"
-                  @pointerenter="selectedIndex = flatIndexOf(c)"
+                  @pointerenter="onPointerEnter(c)"
                 >
                   <LpIcon v-if="c.icon" :name="c.icon" :size="16" class="shrink-0" :class="{ 'mt-0.5': c.excerpt }" />
                   <span class="min-w-0 flex-1">

package/src/components/LpConfirmDialog.vue

@@ -36,10 +36,10 @@ const props = withDefaults(
      */
     loading?: boolean
     loadingLabel?: string
-    /** Frosted glass panel, passed to LpModal. Off by default. */
+    /** Frosted glass panel, passed to LpModal. Follows `provideGlass` when unset. */
     glass?: boolean
   }>(),
-  { confirmLabel: "Confirm", cancelLabel: "Cancel", loadingLabel: "Working…" },
+  { confirmLabel: "Confirm", cancelLabel: "Cancel", loadingLabel: "Working…", glass: undefined },
 )
 
 const emit = defineEmits<{

package/src/components/LpDrawer.vue

@@ -31,6 +31,7 @@ import {
 } from "vaul-vue"
 import { computed, onBeforeUnmount, ref, useSlots, watch } from "vue"
 import { CLOSE_ICON } from "./dropdown"
+import { useGlass } from "../composables/useGlass"
 import LpIcon from "./LpIcon.vue"
 import LpScrollArea from "./LpScrollArea.vue"
 import { anyModalOpen, useModalLayer } from "./modalDepth"
@@ -104,7 +105,8 @@ const props = withDefaults(
     /**
      * Frosted glass instead of a solid panel: the page shows through,
      * blurred, under a lighter scrim (.lp-glass-overlay, .lp-scrim--light).
-     * A look, not a behaviour, so it is the app's call and off by default.
+     * A look, not a behaviour, so it is the app's call: unset follows
+     * `provideGlass`, and without one it is off.
      */
     glass?: boolean
   }>(),
@@ -117,10 +119,12 @@ const props = withDefaults(
     edgeOpenThreshold: 0.3,
     minSize: "22rem",
     maxSize: "96vw",
-    glass: false,
+    glass: undefined,
   },
 )
 
+const frosted = useGlass(() => props.glass)
+
 const emit = defineEmits<{
   (e: "update:open", value: boolean): void
 }>()
@@ -149,7 +153,7 @@ watch(() => props.open, (open) => (open ? claim() : release()), { immediate: tru
 onBeforeUnmount(release)
 
 const contentClass = computed(() => {
-  const surface = props.glass ? "lp-glass-overlay" : "bg-surface-raised"
+  const surface = frosted.value ? "lp-glass-overlay" : "bg-surface-raised"
   const base = `fixed z-(--z-modal) flex flex-col border-line ${surface} shadow-panel outline-none`
   const map: Record<Direction, string> = {
     left: "inset-y-0 left-0 border-r rounded-r-card",
@@ -439,7 +443,7 @@ const previewStyle = computed(() => {
     <div
       v-show="peeking || peek > 0"
       class="lp-scrim pointer-events-none fixed inset-0"
-      :class="{ 'lp-scrim--light': glass }"
+      :class="{ 'lp-scrim--light': frosted }"
       :style="{ zIndex: layer.scrim, opacity: peek, transition: peeking || reducedMotion() ? 'none' : 'opacity 0.18s ease-out' }"
     />
     <div
@@ -472,7 +476,7 @@ const previewStyle = computed(() => {
       <DrawerOverlay
         :style="{ zIndex: layer.scrim }"
         class="lp-scrim fixed inset-0 z-(--z-overlay) data-[state=open]:animate-[fade-in_150ms_ease] data-[state=closed]:animate-[fade-out_130ms_ease]"
-        :class="{ 'lp-scrim--light': glass }"
+        :class="{ 'lp-scrim--light': frosted }"
       />
       <DrawerContent
         :class="contentClass"

package/src/components/LpModal.vue

@@ -9,6 +9,7 @@ import {
   DialogTitle,
 } from "reka-ui"
 import { computed, onBeforeUnmount, ref, useSlots, watch } from "vue"
+import { useGlass } from "../composables/useGlass"
 import { useShift } from "../composables/useShift"
 import { useModalLayer } from "./modalDepth"
 import { CLOSE_ICON } from "./dropdown"
@@ -65,13 +66,16 @@ const props = withDefaults(
     /**
      * Frosted glass instead of a solid panel: the page shows through,
      * blurred, under a lighter scrim (.lp-glass-overlay, .lp-scrim--light).
-     * A look, not a behaviour, so it is the app's call and off by default.
+     * A look, not a behaviour, so it is the app's call: unset follows
+     * `provideGlass`, and without one it is off.
      */
     glass?: boolean
   }>(),
-  { size: "md", autoFocus: "auto", glass: false },
+  { size: "md", autoFocus: "auto", glass: undefined },
 )
 
+const frosted = useGlass(() => props.glass)
+
 defineEmits<{ (e: "update:open", value: boolean): void }>()
 
 // Spread rather than a plain `:aria-describedby` binding: with a description
@@ -228,7 +232,7 @@ watch(
   <DialogRoot :open="open" @update:open="(v) => $emit('update:open', v)">
     <DialogPortal>
       <DialogOverlay
-        :class="{ 'lp-scrim--light': glass }"
+        :class="{ 'lp-scrim--light': frosted }"
         class="lp-scrim fixed inset-0 data-[state=open]:animate-[fade-in_var(--duration-medium)_var(--ease-emphasized)] data-[state=closed]:animate-[fade-out_120ms_ease]"
         :style="{ zIndex: layer.scrim }"
       />
@@ -298,7 +302,7 @@ watch(
       <div
         ref="panelRef"
         class="flex max-h-[min(90vh,calc(100dvh-2rem))] min-h-0 flex-col overflow-hidden rounded-card border border-line shadow-panel"
-        :class="[glass ? 'lp-glass-overlay' : 'bg-surface-raised', widthClass, tweening ? 'transition-[height] duration-fast ease-[var(--ease-emphasized)] motion-reduce:transition-none' : '']"
+        :class="[frosted ? 'lp-glass-overlay' : 'bg-surface-raised', widthClass, tweening ? 'transition-[height] duration-fast ease-[var(--ease-emphasized)] motion-reduce:transition-none' : '']"
         :style="{ ...(width ? { width } : {}), ...(hasAside ? { alignSelf: 'stretch' } : {}) }"
       >
         <header v-if="title || $slots.title" class="flex shrink-0 items-start justify-between gap-4 p-5 pb-3">

package/src/components/LpModalNav.vue

@@ -55,7 +55,7 @@ const props = withDefaults(
      * column inside the body, and the rail is no longer in the body.
      */
     fillBody?: boolean
-    /** Frosted glass panel, passed to LpModal. Off by default. */
+    /** Frosted glass panel, passed to LpModal. Follows `provideGlass` when unset. */
     glass?: boolean
   }>(),
   {
@@ -64,6 +64,7 @@ const props = withDefaults(
     mobileBreakpoint: "lg",
     navLabel: "Sections",
     navSide: "start",
+    glass: undefined,
   },
 )
 

package/src/components/LpShortcutsDialog.vue

@@ -2,40 +2,49 @@
 /*
  * A keyboard reference, conventionally opened with F1.
  *
- * Shortcuts are passed in as data rather than read off a live binding list: a
- * binding knows its key but not what to call it, and in most apps half of them
- * are only mounted in the section they belong to — a reference that lists what
- * happens to be active is not a reference.
+ * Two sources, used together or apart. `groups` is the written list: keys
+ * that are not bindings at all (arrows inside a list, Backspace in a palette)
+ * and the ones worth knowing before their screen is open. `live` adds every
+ * mounted `useHotkeys` binding that carries `help`, so a screen with its own
+ * keys documents them while it is open and drops them when it closes. Groups
+ * of the same title merge, and a combo is listed once.
  *
- * Combos are written the way they read ("Ctrl+Shift+M", "←→↑↓") and split on
- * "+" into one <kbd> each.
+ * Combos are written the way they read ("Ctrl+Shift+M", "Ctrl++", "←→↑↓") and
+ * split on "+" into one <kbd> each.
  */
+import { computed } from "vue"
 import LpModal from "./LpModal.vue"
-import { appleModifierLabel } from "../composables/useHotkeys"
-
-export interface ShortcutEntry {
-  /** Rendered one <kbd> per "+"-separated key, so write it the way it reads. */
-  combo: string
-  label: string
-}
-
-export interface ShortcutGroup {
-  title: string
-  entries: ShortcutEntry[]
-}
+import {
+  activeShortcuts,
+  appleModifierLabel,
+  mergeShortcutGroups,
+  type ShortcutGroup,
+} from "../composables/useHotkeys"
 
 const props = withDefaults(
   defineProps<{
     open?: boolean
-    groups: ShortcutGroup[]
+    groups?: ShortcutGroup[]
+    /** Also list the bindings mounted right now (`useHotkeys` with `help`). */
+    live?: boolean
     title?: string
     description?: string
-    /** Frosted glass panel, passed to LpModal. Off by default. */
+    /** Frosted glass panel, passed to LpModal. Follows `provideGlass` when unset. */
     glass?: boolean
   }>(),
-  { open: false, title: "Keyboard shortcuts" },
+  { open: false, groups: () => [], live: false, title: "Keyboard shortcuts", glass: undefined },
 )
 
+/*
+ * One key per "+", except a "+" that is the key itself: "Ctrl++" is Ctrl and
+ * plus, not Ctrl and two blanks.
+ */
+function keysOf(combo: string): string[] {
+  return combo.split(/\+(?!$)/)
+}
+
+const shown = computed(() => (props.live ? mergeShortcutGroups(props.groups, activeShortcuts.value) : props.groups))
+
 const emit = defineEmits<{ (e: "update:open", value: boolean): void }>()
 </script>
 
@@ -49,13 +58,13 @@ const emit = defineEmits<{ (e: "update:open", value: boolean): void }>()
     @update:open="(value: boolean) => emit('update:open', value)"
   >
     <div class="shortcut-groups">
-      <section v-for="group in props.groups" :key="group.title" class="shortcut-group">
+      <section v-for="group in shown" :key="group.title" class="shortcut-group">
         <h3>{{ group.title }}</h3>
         <dl>
           <div v-for="entry in group.entries" :key="entry.combo" class="shortcut-row">
             <dt>{{ entry.label }}</dt>
             <dd>
-              <kbd v-for="(key, index) in entry.combo.split('+')" :key="`${key}-${index}`">
+              <kbd v-for="(key, index) in keysOf(entry.combo)" :key="`${key}-${index}`">
                 {{ appleModifierLabel(key.trim()) }}
               </kbd>
             </dd>

package/src/composables/useGlass.ts

@@ -0,0 +1,25 @@
+import { computed, inject, provide, toValue, type ComputedRef, type InjectionKey, type MaybeRefOrGetter } from "vue"
+
+/*
+ * Frosted glass as an app-wide default for overlays (modals, drawers, dialogs,
+ * the command palette). An app that wants every overlay frosted says so once
+ * at its root instead of on each of dozens of call sites, where the next new
+ * dialog would be the one that forgets. An explicit `glass` prop on a single
+ * overlay still wins, either way.
+ */
+const GLASS: InjectionKey<MaybeRefOrGetter<boolean>> = Symbol("lp-glass")
+
+/** Make `glass` the default for every overlay below the calling component. */
+export function provideGlass(enabled: MaybeRefOrGetter<boolean> = true): void {
+  provide(GLASS, enabled)
+}
+
+/**
+ * The glass flag an overlay renders with: its own prop when set, otherwise the
+ * nearest `provideGlass`, otherwise off. The prop must default to `undefined`,
+ * not `false`, or an unset prop could not be told apart from an explicit off.
+ */
+export function useGlass(own: () => boolean | undefined): ComputedRef<boolean> {
+  const inherited = inject(GLASS, false)
+  return computed(() => own() ?? toValue(inherited))
+}