@leavepulse/ui 0.69.0 → 0.70.0

package/src/components/LpFrame.vue

@@ -0,0 +1,200 @@
+<script lang="ts">
+// The consumer's `class` is merged into the iframe's own (below) rather than
+// appended to it, so opt out of the automatic pass-through that would add it
+// a second time, unmerged.
+export default { inheritAttrs: false }
+</script>
+
+<script setup lang="ts">
+/*
+ * A window of its own inside the page, as LpThemeProvider is a theme of its
+ * own: what is rendered in it behaves as if it were the whole screen. It is
+ * an iframe the slot is teleported into, so the content stays part of the
+ * same app (its state, theme, config and labels are the page's) while:
+ *
+ * - its width is the viewport: CSS breakpoints (`sm:`, `max-sm:`) and the
+ *   kit's own media queries answer for the frame, so a frame narrowed to a
+ *   phone gets the phone layout, a tour's bottom sheet included;
+ * - the kit's overlays (modals, popovers, menus, the tour, toasts) open
+ *   inside it, not over the page;
+ * - a click outside the frame is not "outside" for what is open in it: a
+ *   notification feed stays open while the page around it is used, and
+ *   Escape pressed on the page does not close it.
+ *
+ * The page's stylesheets and the root element's theme are mirrored into the
+ * frame and kept in step (hot reloads and theme switches included). A modal
+ * in the frame would lock the page's scroll and pointer (reka locks the
+ * global body); the frame lifts such a lock while the page itself has no
+ * layer open. Its height follows the content unless `height` fixes it, which
+ * a screen-sized demo wants: a frame as tall as its content gives a modal
+ * nothing to centre in.
+ */
+import { computed, onBeforeUnmount, onMounted, ref, shallowRef } from "vue"
+import { useMergedAttrs } from "../composables/useMergedClass"
+import { forwardViewEvents, provideView, type LpView } from "../composables/useView"
+
+const props = withDefaults(
+  defineProps<{
+    /** Fixed height (px or any CSS length). Without it the frame grows with its content. */
+    height?: number | string
+    /** Read by assistive technology for the frame as a whole. */
+    title?: string
+  }>(),
+  { title: "Preview" },
+)
+
+const frame = ref<HTMLIFrameElement | null>(null)
+const view = shallowRef<LpView | null>(null)
+provideView(computed(() => view.value))
+
+const contentHeight = ref(0)
+const fixed = computed(() =>
+  props.height === undefined ? undefined : typeof props.height === "number" ? `${props.height}px` : props.height,
+)
+
+// Height eases, so a frame switched to a device screen or grown by an
+// opening popover does not jump.
+const { class: frameClass, attrs: rest } = useMergedAttrs(
+  "block w-full border-0 bg-transparent transition-[height] duration-(--duration-medium) ease-(--ease-emphasized) motion-reduce:transition-none",
+)
+
+const cleanups: (() => void)[] = []
+
+function mirrorHead(doc: Document) {
+  const copies = new Map<Node, Node>()
+  const copy = (node: Node) => {
+    if (!(node instanceof HTMLStyleElement || (node instanceof HTMLLinkElement && node.rel === "stylesheet"))) return
+    const clone = doc.importNode(node, true)
+    copies.set(node, clone)
+    doc.head.appendChild(clone)
+  }
+  for (const node of document.head.childNodes) copy(node)
+  const observer = new MutationObserver((records) => {
+    for (const record of records) {
+      if (record.type === "childList") {
+        for (const node of record.addedNodes) copy(node)
+        for (const node of record.removedNodes) {
+          copies.get(node)?.parentNode?.removeChild(copies.get(node)!)
+          copies.delete(node)
+        }
+        continue
+      }
+      // A style rewritten in place (a hot reload) is copied again.
+      const style = record.target instanceof HTMLStyleElement ? record.target : record.target.parentNode
+      if (style instanceof HTMLStyleElement && copies.has(style)) copies.get(style)!.textContent = style.textContent
+    }
+  })
+  observer.observe(document.head, { childList: true, subtree: true, characterData: true })
+  cleanups.push(() => observer.disconnect())
+}
+
+// The theme lives on the page's root element (its class, data attributes and
+// token variables); the frame's root carries the same, so it themes as one.
+function mirrorRoot(doc: Document) {
+  const sync = () => {
+    const from = document.documentElement
+    const to = doc.documentElement
+    for (const name of to.getAttributeNames()) if (!from.hasAttribute(name)) to.removeAttribute(name)
+    for (const name of from.getAttributeNames()) to.setAttribute(name, from.getAttribute(name) ?? "")
+  }
+  sync()
+  const observer = new MutationObserver(sync)
+  observer.observe(document.documentElement, { attributes: true })
+  cleanups.push(() => observer.disconnect())
+}
+
+// reka's modal locks `document.body` of the page whatever document the layer
+// is in. The lock is the page's only when the page has a layer of its own.
+function liftForeignLocks(doc: Document) {
+  const lift = () => {
+    if (!doc.querySelector("[data-dismissable-layer]")) return
+    if (document.querySelector("[data-dismissable-layer]")) return
+    const style = document.body.style
+    if (style.pointerEvents === "none") style.pointerEvents = ""
+    if (style.overflow === "hidden") {
+      style.overflow = ""
+      style.paddingRight = ""
+      style.marginRight = ""
+    }
+  }
+  const observer = new MutationObserver(lift)
+  observer.observe(document.body, { attributes: true, attributeFilter: ["style"] })
+  cleanups.push(() => observer.disconnect())
+}
+
+function setup() {
+  const win = frame.value?.contentWindow
+  const doc = frame.value?.contentDocument
+  if (!win || !doc) return
+  // Relative URLs in the copied styles (fonts, images) resolve against the page.
+  const base = doc.createElement("base")
+  base.href = document.baseURI
+  doc.head.appendChild(base)
+  doc.body.style.margin = "0"
+  doc.body.style.background = "transparent"
+  mirrorHead(doc)
+  mirrorRoot(doc)
+  liftForeignLocks(doc)
+  cleanups.push(forwardViewEvents(doc, document))
+  const content = doc.createElement("div")
+  doc.body.appendChild(content)
+  // Grown to fit the content and whatever is open over it: a popover hanging
+  // below the last line would otherwise be cut off at the frame's edge.
+  let pending = 0
+  const measure = () => {
+    pending = 0
+    let bottom = content.offsetHeight
+    for (const child of doc.body.children) {
+      if (child === content) continue
+      for (const layer of child.querySelectorAll("[data-dismissable-layer], [role=dialog], [role=menu], [role=listbox]")) {
+        bottom = Math.max(bottom, Math.ceil(layer.getBoundingClientRect().bottom + 8))
+      }
+    }
+    contentHeight.value = bottom
+  }
+  const schedule = () => {
+    if (!pending) pending = win.requestAnimationFrame(measure)
+  }
+  const Observer = (win as Window & typeof globalThis).ResizeObserver
+  const resize = new Observer(schedule)
+  resize.observe(content)
+  const layers = new (win as Window & typeof globalThis).MutationObserver(schedule)
+  layers.observe(doc.body, { childList: true, subtree: true })
+  cleanups.push(() => {
+    resize.disconnect()
+    layers.disconnect()
+    if (pending) win.cancelAnimationFrame(pending)
+  })
+  view.value = { window: win, document: doc, portal: doc.body }
+  root.value = content
+}
+
+const root = shallowRef<HTMLElement | null>(null)
+
+onMounted(() => {
+  const el = frame.value
+  if (!el) return
+  // about:blank is ready synchronously in Chromium and WebKit, but Firefox
+  // swaps the document on load: wait for it there.
+  if (el.contentDocument?.readyState === "complete") setup()
+  else el.addEventListener("load", setup, { once: true })
+})
+
+onBeforeUnmount(() => {
+  for (const clean of cleanups) clean()
+  cleanups.length = 0
+})
+</script>
+
+<template>
+  <iframe
+    ref="frame"
+    :title="title"
+    :class="frameClass"
+    :style="{ height: fixed ?? `${contentHeight}px` }"
+    v-bind="rest"
+  />
+  <Teleport v-if="root" :to="root">
+    <slot />
+  </Teleport>
+</template>

package/src/components/LpGauge.vue

@@ -0,0 +1,287 @@
+<script lang="ts">
+// The consumer's `class` is merged into the root's own rather than appended to
+// it, so opt out of the automatic pass-through that would add it unmerged.
+export default { inheritAttrs: false }
+</script>
+
+<script setup lang="ts">
+/*
+ * One reading within a range, drawn as a dial: CPU load, disk use, a score.
+ *
+ * Not a variant of LpProgress's ring, though both draw an arc. The ring is
+ * progress toward done: it starts at zero, closes into a circle at 100 and has
+ * no idea what the number means. A gauge is a reading on a scale: it has a
+ * floor that need not be zero, steps along the way where the reading changes
+ * meaning (the threshold notches), and a sweep with a visible start and end so
+ * the eye can tell low from high without reading the figure. Folding that into
+ * the ring would grow it a second set of props that only apply in one variant.
+ * The arithmetic both need (fraction of a range, tone at a reading) lives in
+ * meter.ts and is shared rather than copied.
+ */
+import { computed } from "vue"
+import { useLabels } from "../composables/useLpConfig"
+import { useLocale } from "../composables/useLocale"
+import { useMergedAttrs } from "../composables/useMergedClass"
+import { useRevealedValue } from "../composables/useRevealedValue"
+import LpNumberFlow from "./LpNumberFlow.vue"
+import LpRollingText from "./LpRollingText.vue"
+import {
+  arcPath,
+  capacityThresholds,
+  GAUGE_SWEEP,
+  meterFraction,
+  polar,
+  toneAt,
+  type MeterThreshold,
+  type MeterTone,
+} from "./meter"
+import { toneLook } from "./tone"
+
+export type GaugeLabels = {
+  /** Appended to the spoken value when the reading is in a warning step. */
+  warning: string
+  /** Appended to the spoken value when the reading is in a danger step. */
+  danger: string
+}
+
+const props = withDefaults(
+  defineProps<{
+    value: number
+    min?: number
+    max?: number
+    /**
+     * Steps of the scale, in the gauge's own units: from each `at` upward the
+     * arc takes that tone. Unset, the capacity scale applies (warning from 80%
+     * of the range, danger from 90%), which is what a resource gauge wants. A
+     * score where higher is better lists its own steps:
+     * `[{ at: 0, tone: 'danger' }, { at: 50, tone: 'warning' }, { at: 80, tone: 'ok' }]`.
+     */
+    thresholds?: MeterThreshold[]
+    /**
+     * A fixed tone instead of the scale. For a gauge whose reading is neither
+     * good nor bad (a temperature, a position), where colouring it by
+     * thresholds would invent a judgement.
+     */
+    tone?: MeterTone
+    /** What is measured, printed under the figure ("CPU", "Disk"). Also the accessible name. */
+    label?: string
+    /** Printed after the figure, smaller ("%", "°C", "ms"). */
+    unit?: string
+    /** Decimal places of the figure. */
+    decimals?: number
+    /**
+     * Says the figure differently ("1.2k", "3/8"). Overrides `decimals`; the
+     * figure still rolls, since the formatted string is what LpNumberFlow animates.
+     */
+    format?: (value: number) => string
+    /** `semi` (default) sweeps across the top; `full` is a 270° dial open at the bottom. */
+    variant?: "semi" | "full"
+    /** Width in px. The height follows from the shape. */
+    size?: number
+    /** Arc thickness in px. Defaults to a share of `size`. */
+    thickness?: number
+    /** Print `min` and `max` under the ends of the arc. On by default for `semi`, where they sit naturally. */
+    showRange?: boolean
+    /** Notch the track where each threshold starts, so the reader sees how far the next step is. */
+    showThresholds?: boolean
+    /**
+     * Sweep up from the floor when first seen, instead of appearing already
+     * at the reading. Later changes always ease from where the needle is.
+     */
+    animateOnMount?: boolean
+    /** Sweep length in ms, shared by the arc and the figure. */
+    duration?: number
+    locale?: string
+    labels?: Partial<GaugeLabels>
+  }>(),
+  {
+    min: 0,
+    max: 100,
+    decimals: 0,
+    variant: "semi",
+    size: 160,
+    showRange: undefined,
+    showThresholds: true,
+    animateOnMount: true,
+    // Same as LpProgress: a gauge filling is content, and at the kit's
+    // `slow` step the sweep is over before it is noticed.
+    duration: 900,
+  },
+)
+
+const text = useLabels<GaugeLabels>("gauge", { warning: "warning", danger: "critical" }, () => props.labels)
+const locale = useLocale(() => props.locale)
+
+/*
+ * One animated number drives both the arc and the figure, as in LpProgress:
+ * two animations of the same length still drift apart through the middle,
+ * because they ease on different curves.
+ */
+const { el: revealAnchor, shown } = useRevealedValue(() => props.value, {
+  from: () => props.min,
+  animateOnMount: () => props.animateOnMount,
+  duration: () => props.duration,
+})
+
+const steps = computed(() => props.thresholds ?? capacityThresholds(props.min, props.max))
+
+/*
+ * The tone follows the TARGET, not the sweeping value, so the arc does not
+ * flash through amber on its way down from red: it travels in the colour its
+ * reading warrants.
+ */
+const paintedTone = computed<MeterTone>(() => props.tone ?? toneAt(props.value, steps.value))
+
+const thick = computed(() => props.thickness ?? Math.max(4, Math.round(props.size * 0.075)))
+const sweep = computed(() => GAUGE_SWEEP[props.variant])
+// Threshold notches sit just outside the arc, so the arc gives up their room.
+const NOTCH = 5
+const radius = computed(() => (props.size - thick.value) / 2 - (props.showThresholds ? NOTCH : 0))
+const cx = computed(() => props.size / 2)
+const cy = computed(() => props.size / 2)
+// A semicircle needs only its top half plus the round caps hanging below the
+// ends; the full dial needs the square.
+const height = computed(() =>
+  props.variant === "semi" ? Math.ceil(cy.value + thick.value / 2) : props.size,
+)
+
+const track = computed(() => arcPath(cx.value, cy.value, radius.value, sweep.value[0], sweep.value[1]))
+const fraction = computed(() => meterFraction(shown.value, props.min, props.max))
+
+/*
+ * The value arc is the track path dashed to length, with `pathLength` so the
+ * dash is a plain share of 1000 whatever the radius. At zero a round-capped
+ * zero-length dash still draws a dot, so the arc hides instead.
+ */
+const dash = computed(() => `${(fraction.value * 1000).toFixed(2)} 1000`)
+
+const notches = computed(() => {
+  if (!props.showThresholds) return []
+  const [from, to] = sweep.value
+  const inner = radius.value + thick.value / 2 + 1.5
+  const outer = inner + NOTCH - 1
+  return steps.value
+    .filter((s) => s.at > props.min && s.at < props.max)
+    .map((s) => {
+      const deg = from + (to - from) * meterFraction(s.at, props.min, props.max)
+      const a = polar(cx.value, cy.value, inner, deg)
+      const b = polar(cx.value, cy.value, outer, deg)
+      return { key: `${s.at}-${s.tone}`, a, b, color: toneLook(s.tone).color }
+    })
+})
+
+const rangeShown = computed(() => props.showRange ?? props.variant === "semi")
+
+const formatter = computed(() => {
+  if (props.format) return props.format
+  const nf = new Intl.NumberFormat(locale.value, {
+    minimumFractionDigits: props.decimals,
+    maximumFractionDigits: props.decimals,
+  })
+  return (v: number) => nf.format(v)
+})
+
+const valueText = computed(() => {
+  const reading = `${formatter.value(props.value)}${props.unit ? ` ${props.unit}` : ""}`
+  const tone = paintedTone.value
+  return tone === "warning" || tone === "danger" ? `${reading}, ${text.value[tone]}` : reading
+})
+
+const { class: rootClass, attrs: rest } = useMergedAttrs(
+  "relative inline-flex shrink-0 flex-col items-center",
+)
+const figureSize = computed(() => `${Math.max(14, Math.round(props.size * 0.19))}px`)
+</script>
+
+<template>
+  <div
+    :ref="(el) => (revealAnchor = el as Element | null)"
+    role="meter"
+    :aria-valuenow="value"
+    :aria-valuemin="min"
+    :aria-valuemax="max"
+    :aria-valuetext="valueText"
+    :aria-label="label"
+    :class="rootClass"
+    :style="{ width: `${size}px` }"
+    v-bind="rest"
+  >
+    <div class="relative">
+      <svg
+        :width="size"
+        :height="height"
+        :viewBox="`0 0 ${size} ${height}`"
+        class="overflow-visible"
+        aria-hidden="true"
+      >
+        <path
+          :d="track"
+          fill="none"
+          stroke="var(--color-surface-soft)"
+          :stroke-width="thick"
+          stroke-linecap="round"
+        />
+        <path
+          :d="track"
+          fill="none"
+          pathLength="1000"
+          :stroke="toneLook(paintedTone).color"
+          :stroke-width="thick"
+          stroke-linecap="round"
+          :stroke-dasharray="dash"
+          :opacity="fraction > 0.0005 ? 1 : 0"
+          class="transition-[stroke] duration-(--duration-slow) ease-(--ease-emphasized) motion-reduce:transition-none"
+        />
+        <line
+          v-for="n in notches"
+          :key="n.key"
+          :x1="n.a.x"
+          :y1="n.a.y"
+          :x2="n.b.x"
+          :y2="n.b.y"
+          :stroke="n.color"
+          stroke-width="2"
+          stroke-linecap="round"
+        />
+      </svg>
+
+      <!-- The figure sits in the bowl of the arc: on its baseline for the
+           semicircle, in the middle for the dial. -->
+      <div
+        class="pointer-events-none absolute inset-x-0 flex flex-col items-center leading-none"
+        :class="variant === 'semi' ? 'bottom-0' : 'top-1/2 -translate-y-1/2'"
+      >
+        <span class="flex items-baseline gap-0.5 font-mono font-semibold text-ink" :style="{ fontSize: figureSize }">
+          <LpNumberFlow
+            :value="shown"
+            :decimals="decimals"
+            :format="format"
+            :locale="locale"
+            :duration="0"
+            :animate-on-mount="false"
+            :style="{ '--lp-nf-spin': '90ms' }"
+          />
+          <span v-if="unit" class="text-[0.55em] font-medium text-muted">{{ unit }}</span>
+        </span>
+        <span v-if="label && variant === 'full'" class="mt-1 text-xs text-muted">
+          <LpRollingText :value="label" />
+        </span>
+      </div>
+    </div>
+
+    <!-- Under a semicircle the label shares the baseline row with the range
+         ends rather than stacking under the figure inside the bowl: a small
+         gauge has no room for both there, and the figure ran into the arc. -->
+    <div
+      v-if="rangeShown || (label && variant === 'semi')"
+      class="mt-1 grid w-full grid-cols-[1fr_auto_1fr] items-baseline gap-2 text-[11px] text-muted"
+      :style="{ paddingInline: `${Math.max(0, cx - radius - thick / 2)}px` }"
+    >
+      <span class="font-mono tabular-nums" aria-hidden="true">{{ rangeShown ? formatter(min) : "" }}</span>
+      <span class="truncate text-xs">
+        <LpRollingText v-if="label && variant === 'semi'" :value="label" />
+      </span>
+      <span class="text-right font-mono tabular-nums" aria-hidden="true">{{ rangeShown ? formatter(max) : "" }}</span>
+    </div>
+  </div>
+</template>

package/src/components/LpGlowBorder.vue

@@ -0,0 +1,60 @@
+<script lang="ts">
+export default { inheritAttrs: false }
+</script>
+
+<script setup lang="ts">
+/*
+ * LpGlowBorder — a gradient that runs round the edge of whatever it wraps.
+ *
+ *   <LpGlowBorder><LpCard>Recommended build</LpCard></LpGlowBorder>
+ *
+ * For the ONE item in a list that should be noticed first: a new release, the
+ * recommended option. Several glowing borders on one screen cancel each other
+ * out, so this is a highlight, not a style.
+ *
+ * Pure CSS (`.lp-glow-border` in tokens/effects.css): a conic gradient whose
+ * angle is an animated registered property. Without @property support (older
+ * WebKitGTK) the ring stays still as a static gradient border, and reduced
+ * motion stops it the same way. The ring takes no layout space: it sits just
+ * outside the wrapped element's edge, following `rounded-card` by default —
+ * pass a radius class matching the child if it is not a card.
+ */
+import { computed } from "vue"
+import { useMergedAttrs } from "../composables/useMergedClass"
+
+const props = withDefaults(
+  defineProps<{
+    /** Leading colour of the gradient. Defaults to the brand colour. */
+    from?: string
+    /** Trailing colour of the gradient. Defaults to the action colour. */
+    to?: string
+    /** Ring thickness in px. */
+    width?: number
+    /** Seconds per revolution. Slower reads as calm, faster as urgent. */
+    speed?: number
+    /**
+     * Light the ring. Off keeps the wrapper (so the layout does not change when
+     * an item stops being "new") and removes only the ring.
+     */
+    active?: boolean
+    /** Element to render as. */
+    as?: string
+  }>(),
+  { width: 1.5, speed: 4, active: true, as: "div" },
+)
+
+const { class: classes, attrs: rest } = useMergedAttrs(() => "lp-glow-border rounded-card")
+
+const style = computed(() => ({
+  "--lp-glow-width": `${props.width}px`,
+  "--lp-glow-speed": `${props.speed}s`,
+  ...(props.from ? { "--lp-glow-from": props.from } : {}),
+  ...(props.to ? { "--lp-glow-to": props.to } : {}),
+}))
+</script>
+
+<template>
+  <component :is="as" :class="classes" :style="style" :data-lp-glow-off="active ? undefined : ''" v-bind="rest">
+    <slot />
+  </component>
+</template>

package/src/components/LpHintExample.vue

@@ -31,9 +31,9 @@
  * card still says it is an example.
  */
 import { computed, watch } from "vue"
-import { durationToken, easingToken, prefersReducedMotion } from "../composables/easing"
 import { hints } from "../composables/useHints"
 import HintSampleTag from "./HintSampleTag.vue"
+import LpCollapse from "./LpCollapse.vue"
 
 const props = defineProps<{
   /** The hint id this stands in for, as in `v-hint`, or several for a sample with parts. */
@@ -59,26 +59,10 @@ watch(
 
 const visible = computed(() => absent.value.some((id) => hints.showingExample(id)))
 
-// The block grows from nothing and shrinks back, so what sits below it glides
-// instead of jumping. It exists only while shown: an always-present wrapper
-// would take a gap in the parent's flex column even when empty.
-
-function grow(el: Element, done: () => void, opening: boolean) {
-  if (prefersReducedMotion()) return done()
-  const box = el as HTMLElement
-  const frames = [
-    { height: "0px", opacity: 0 },
-    { height: `${box.scrollHeight}px`, opacity: 1 },
-  ]
-  box.style.overflow = "hidden"
-  box.animate(opening ? frames : frames.reverse(), {
-    duration: durationToken("duration-medium"),
-    easing: easingToken("ease-emphasized"),
-  }).onfinish = () => {
-    box.style.overflow = ""
-    done()
-  }
-}
+// The block folds open from nothing and shut again (LpCollapse), so what sits
+// below it glides instead of jumping. It exists only while shown (the collapse
+// unmounts it once folded): an always-present wrapper would take a gap in the
+// parent's flex column even when empty.
 </script>
 
 <template>
@@ -93,15 +77,8 @@ function grow(el: Element, done: () => void, opening: boolean) {
       <slot />
     </span>
   </Transition>
-  <Transition
-    v-else
-    :css="false"
-    @enter="(el, done) => grow(el, done, true)"
-    @leave="(el, done) => grow(el, done, false)"
-  >
-    <div v-if="visible" :data-lp-hint-example="ids.join(' ')" inert aria-hidden="true" class="relative">
-      <slot />
-      <HintSampleTag :labels="labels" />
-    </div>
-  </Transition>
+  <LpCollapse v-else :open="visible" :data-lp-hint-example="ids.join(' ')" inert aria-hidden="true" class="relative">
+    <slot />
+    <HintSampleTag :labels="labels" />
+  </LpCollapse>
 </template>

package/src/components/LpHintLayer.vue

@@ -20,7 +20,9 @@ import { computed, onBeforeUnmount, onMounted, ref, shallowRef, watch } from "vu
 import { hints } from "../composables/useHints"
 import { useLabels } from "../composables/useLpConfig"
 import { PANEL_SURFACE, POPOVER_ANIM } from "./dropdown"
+import LpBadge from "./LpBadge.vue"
 import LpButton from "./LpButton.vue"
+import { useOutsideGuard, usePortalTarget } from "../composables/useView"
 
 const props = withDefaults(
   defineProps<{
@@ -104,10 +106,16 @@ onBeforeUnmount(() => {
 })
 
 const note = computed(() => (openId.value ? props.notes[openId.value] : undefined))
+
+// Overlays open in the window this component renders in (an LpFrame's, inside one).
+const portalTo = usePortalTarget()
+// What happens in another document (the page around a frame, or a frame in
+// the page) is not "outside" for this layer.
+const guardOutside = useOutsideGuard()
 </script>
 
 <template>
-  <Teleport to="body">
+  <Teleport :to="portalTo">
     <button
       v-for="spot in spots"
       :key="spot.id"
@@ -126,15 +134,17 @@ const note = computed(() => (openId.value ? props.notes[openId.value] : undefine
     </button>
     <PopoverRoot :open="!!openId" @update:open="(value) => !value && (openId = null)">
       <PopoverAnchor v-if="anchor" :reference="anchor" />
-      <PopoverPortal>
+      <PopoverPortal :to="portalTo">
         <PopoverContent
+          @interact-outside="guardOutside"
+          @escape-key-down="guardOutside"
           side="bottom"
           :side-offset="8"
           :collision-padding="8"
           :class="[PANEL_SURFACE, POPOVER_ANIM, 'z-(--z-popover) w-72 rounded-card p-3 text-sm text-ink outline-none']"
         >
           <p class="flex items-center gap-2 font-medium">
-            <span class="rounded-full bg-brand/15 px-1.5 text-[11px] text-brand">{{ labels.badge }}</span>
+            <LpBadge tone="brand" size="sm">{{ labels.badge }}</LpBadge>
             {{ note?.title }}
           </p>
           <p v-if="note?.text" class="mt-1.5 text-muted">{{ note.text }}</p>