@cardstack/boxel-cli 0.10.0 → 0.10.1-unstable.0

package/bundled-realms/pretui/components/popover.gts

@@ -0,0 +1,198 @@
+// Pretui — Popover: an anchored panel with backdrop close and Escape from anywhere.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { modifier } from 'ember-modifier';
+import { listenDocumentCapture } from '../focus';
+import { emit } from '../pretui-primitives';
+import { resolvePlacement, resolveOpen } from '../internal/overlay';
+import type { PopupPlacement, PlacementArgs, OpenArgs } from '../internal/overlay';
+import { Popup } from './popup';
+
+export interface PopoverSignature {
+  Args: OpenArgs &
+    PlacementArgs & {
+      placement?: PopupPlacement | string;
+      distance?: number;
+      label?: string;
+      /** the uncontrolled half of the hybrid */
+      defaultOpen?: boolean;
+      /** fires on every open and close, controlled or not */
+      onOpenChange?: (open: boolean) => void;
+    };
+  Blocks: {
+    trigger: [open: boolean, toggle: () => void];
+    default: [close: () => void];
+  };
+  Element: HTMLSpanElement;
+}
+
+// Anything that can hold focus inside the anchor. Used to hand focus back to
+// the control the panel was opened from — the panel's trigger is a caller
+// block, so the component cannot capture the button directly the way
+// MorphingPopover does.
+const FOCUSABLE =
+  'a[href], button:not(:disabled), input:not(:disabled), select:not(:disabled), textarea:not(:disabled), [tabindex]:not([tabindex="-1"])';
+
+/**
+ * Anchored floating panel: Popup positioning + the generalized backdrop-close
+ * pattern (viewport-covering close target instead of a document listener).
+ *
+ * Escape closes it from anywhere — the trigger, the panel, or a control that
+ * portalled its own DOM elsewhere. **Fixed 2026-08-13:** the listener used to
+ * sit on the panel, so the ordinary path (open from the trigger, press
+ * Escape without tabbing in) did nothing, and that bug rode into every
+ * consumer — `DatePicker`, `DateRangePicker`, `ThemeFrame`. It now uses
+ * `listenDocumentCapture` (focus.gts), installed on the panel so its lifetime
+ * is exactly the open lifetime, in the CAPTURE phase with `stopPropagation`
+ * so a host that also listens for Escape cannot make one keypress mean two
+ * things. This is the 46f065-popover fork's rule — the overlay owns
+ * dismissal, full stop — and the same idiom `MorphingPopover` already uses.
+ *
+ * Every dismissal path returns focus to the trigger.
+ *
+ * **Hybrid since 2026-08-13.** It was uncontrolled-only and emitted no event
+ * at all: a parent could neither open it nor learn that it had opened, which
+ * is the ship-blocking shape ("a control that mutates state without a
+ * callback"). It now carries the kit's controlled/uncontrolled triple —
+ * `@open` / `@defaultOpen` / `@onOpenChange` — and every existing caller,
+ * all of which pass none of the three, keeps the exact behaviour it had.
+ */
+export class Popover extends Component<PopoverSignature> {
+  @tracked internalOpen = this.args.defaultOpen ?? false;
+  private anchorEl?: HTMLElement;
+  captureAnchor = modifier((el: HTMLElement) => {
+    this.anchorEl = el;
+  });
+  get controlled() {
+    return resolveOpen(this.args);
+  }
+  get open() {
+    return this.controlled ?? this.internalOpen;
+  }
+  /** side/align/position/direction fold into @placement before forwarding */
+  get placement(): PopupPlacement {
+    return resolvePlacement(this.args, 'bottom-start');
+  }
+  private setOpen(next: boolean) {
+    if (this.controlled === undefined) {
+      this.internalOpen = next;
+    }
+    emit([this.args.onOpenChange], next);
+  }
+  toggle = () => {
+    this.setOpen(!this.open);
+  };
+  close = () => {
+    if (!this.open) return;
+    this.setOpen(false);
+    this.restoreFocus();
+  };
+  // Focus RETURN. The native <dialog> gives this for free; an anchored panel
+  // has to do it, and almost none of them do. The trigger is a caller block,
+  // so the first focusable in the anchor that is not inside the floating
+  // layer is the best available answer.
+  private restoreFocus() {
+    let root = this.anchorEl;
+    if (!root) return;
+    for (let el of root.querySelectorAll<HTMLElement>(FOCUSABLE)) {
+      if (!el.closest('.pretui-popup')) {
+        el.focus();
+        return;
+      }
+    }
+  }
+  onKey = (e: Event) => {
+    if (!this.open) return;
+    if ((e as KeyboardEvent).key !== 'Escape') return;
+    e.stopPropagation();
+    e.preventDefault();
+    this.close();
+  };
+  <template>
+    <span
+      class='pretui-popover'
+      data-test-pretui-popover
+      {{this.captureAnchor}}
+      ...attributes
+    >
+      <Popup
+        @open={{this.open}}
+        @placement={{this.placement}}
+        @distance={{@distance}}
+      >
+        <:anchor>{{yield this.open this.toggle to='trigger'}}</:anchor>
+        <:default>
+          <button
+            type='button'
+            class='pretui-popover-backdrop'
+            aria-label='Close'
+            tabindex='-1'
+            {{on 'click' this.close}}
+          ></button>
+          <div
+            class='pretui-popover-panel'
+            role='dialog'
+            aria-label={{if @label @label 'Popover'}}
+            tabindex='-1'
+            {{listenDocumentCapture 'keydown' this.onKey}}
+          >
+            {{yield this.close}}
+          </div>
+        </:default>
+      </Popup>
+    </span>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-popover {
+          display: inline-block;
+        }
+        .pretui-popover-backdrop {
+          /* wave-0 backdrop-close: viewport-covering close target instead of a
+             document listener; fixed is intentional (lint warns, accepted) */
+          position: fixed;
+          inset: 0;
+          background: transparent;
+          border: 0;
+          padding: 0;
+          cursor: default;
+        }
+        .pretui-popover-panel {
+          position: relative;
+          background: var(--popover);
+          color: var(--popover-foreground);
+          border-radius: 10px;
+          box-shadow: var(--pretui-shadow-overlay, 0 0 0 1px var(--border), 0 8px 28px rgb(0 0 0 / 0.16));
+          padding: var(--space-4, 11px);
+          /* component-owned knobs: consumers size the panel by setting these
+             custom properties on any ancestor — no :deep() required */
+          width: var(--pretui-popover-width, auto);
+          min-width: var(--pretui-popover-min-width, 200px);
+          max-width: var(--pretui-popover-max-width, min(360px, calc(100vw - 16px)));
+          /* The documented exception to "never remove an outline without a
+             :focus-visible replacement": the panel is tabindex='-1' and is only
+             ever focused programmatically on open, so :focus-visible never
+             matches it and a ring here would only be a stray box around a
+             region the user did not tab to. Every focusable thing INSIDE the
+             panel keeps its own ring. */
+          outline: none;
+          opacity: 1;
+          transform: none;
+          transition: opacity 180ms cubic-bezier(0.23, 1, 0.32, 1),
+            transform 180ms cubic-bezier(0.23, 1, 0.32, 1);
+        }
+        @starting-style {
+          .pretui-popover-panel {
+            opacity: 0;
+            transform: translateY(4px);
+          }
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-popover-panel {
+            transition: none;
+          }
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/popover.md

@@ -0,0 +1,57 @@
+## What it is
+
+A non-modal floating panel anchored to a trigger, holding arbitrary content. Reach for it when a user needs to see or edit something _alongside_ the page rather than instead of it: a filter panel, a colour picker, a quick-edit form, a "details" card off an inline reference. If the content is a flat list of commands, use **Menu**. If the interaction must block the page, use **Dialog** or **Drawer**. If it is a passive one-line hint that appears on hover, use **Tooltip**.
+
+## The contract
+
+```
+@placement? (PopupPlacement, default 'bottom-start'), @distance? (default 6), @label? (default 'Popover')
+<:trigger as |open toggle|>  <:default as |close|>
+```
+
+Two decisions.
+
+**It owns its open state.** There is no `@open`/`@onOpenChange` pair. The trigger block gets `(open, toggle)` so it can render its own expanded affordance, and the default block gets `close` so panel content can dismiss itself after committing — the "Apply" button in a filter popover calls `close` directly. This makes the common case a two-line call site; it also means you cannot open a Popover programmatically or coordinate two of them. If you need that, compose **Popup** yourself.
+
+**Dismissal is a real element, not a document listener.** While open, the panel renders a transparent, viewport-covering `<button tabindex="-1">` behind itself; clicking it closes. This is the kit's generalisation of the Select backdrop-close pattern. It is deliberately not a `document.addEventListener('click', …)`: a document listener has to be attached and removed in lifecycle hooks, can outlive teardown, fires during capture in ways that fight nested overlays, and does not work cleanly inside a scoped island. A DOM node's lifetime _is_ the open state, so there is nothing to leak.
+
+Panel width is set by three component-owned custom properties — `--pretui-popover-width`, `--pretui-popover-min-width` (200px), `--pretui-popover-max-width` (`min(360px, 100vw - 16px)`) — settable from any ancestor, so no `:deep()` is ever required to resize one.
+
+## Prior art
+
+**Radix `Popover`** composes `Root/Trigger/Anchor/Portal/Content/Arrow/Close`, is controlled via `open`/`onOpenChange`/`defaultOpen`, and adds `modal`, `collisionPadding`, `avoidCollisions`, `onEscapeKeyDown`, `onPointerDownOutside`, and full focus management (`onOpenAutoFocus`/`onCloseAutoFocus`). **Web Awesome `wa-popover`** takes `open`, `placement`, `distance`, `skidding`, `without-arrow` and a `for` attribute that associates it to a trigger by id. **React Spectrum** models it as `DialogTrigger type="popover"` and reuses the whole dialog machinery, including `isNonModal`.
+
+Where Pretui differs:
+
+- **The backdrop element instead of outside-click detection** (above) — smaller, leak-free, and correct inside the theme island.
+- **No portal.** Everything else here portals to `document.body`; Pretui renders in place so theme tokens and scoped styles apply. The cost is that a Popover inside `overflow: hidden` relies on `Popup`'s `position: fixed` to escape clipping, which works, but the panel still sits in the anchor's stacking context.
+- **`close` yielded to content** rather than a separate `Popover.Close` component. One fewer export, and it composes with any control.
+- **`--pretui-popover-*` sizing knobs.** Radix leaves width to the consumer's CSS and exposes `--radix-popover-trigger-width` as a read; Pretui inverts it into three writable knobs with sane defaults.
+
+Missing versus the field: no arrow, no `skidding`, no `collisionPadding` (the gutter is a fixed 8px in `anchorTo`), no `modal` mode, no controlled API.
+
+## Accessibility
+
+Governing pattern: APG **Dialog (Non-Modal)**.
+
+Present: `role="dialog"` on the panel, `aria-label` from `@label` (defaulting to the unhelpful literal `'Popover'`), `tabindex="-1"` so the panel is programmatically focusable, Escape closing while focus is inside the panel or on the trigger, and an `aria-label="Close"` backdrop that is `tabindex="-1"` so it never appears in tab order.
+
+Gaps, plainly:
+
+- **Focus is never moved into the panel on open, and never restored to the trigger on close.** APG's non-modal dialog pattern expects both. In practice a keyboard user opens the Popover and then has to Tab forward through it, and after closing, focus is wherever it was.
+- **Escape only works if focus is already inside the panel** — the `keydown` handler is on the panel, not on the wrapper. Open the Popover by clicking the trigger, leave focus on the trigger, press Escape: nothing happens. This is a real bug, not a design choice.
+- **The trigger is not wired.** `aria-haspopup="dialog"`, `aria-expanded` and `aria-controls` are the caller's responsibility; the yielded `open` flag is the raw material but nothing applies it.
+- **`@label` defaults to `'Popover'`**, which is worse than no label in a page with several. Always pass one.
+- No focus containment, correctly — it is non-modal, and Tab should be able to leave.
+
+## Theming
+
+`--popover`, `--popover-foreground` (falling back to `--foreground`), `--pretui-shadow-overlay`, `--space-4`, plus the three `--pretui-popover-*` sizing knobs. Radius is hard-coded at 10px rather than reading `--radius-surface` — a genuine inconsistency with Dialog and Panel that a theme cannot currently override. Entry motion is `@starting-style` (opacity + 4px rise, 180ms) with a `prefers-reduced-motion` opt-out.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+Click-to-open rich surface. Hover preview is **HoverCard**. String
+hint is **Tooltip**. Confirm-next-to-trigger is **Popconfirm**.
+Accept `open` / `onOpenChange` / `side` / `align` → `@placement`.

package/bundled-realms/pretui/components/popover.usage.gts

@@ -0,0 +1,106 @@
+// Pretui — Popover usage page.
+import GlimmerComponent from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { FreestyleUsage } from './freestyle-usage';
+import { Popover } from './popover';
+import type { PopupPlacement } from '../internal/overlay';
+import { Button } from './button';
+import { PLACEMENT_OPTIONS } from '../demo-structure';
+
+// Dropped knobs: contentClass (no class arg); variant (styling rides theme
+// tokens); matchTriggerWidth (exposed on the Popup primitive as @matchWidth,
+// not on Popover); registerAPI (no public-API object — the trigger block
+// yields open/toggle instead); onClose + autoClose (backdrop click and
+// Escape close the panel by design).
+class PopoverUsage extends GlimmerComponent {
+  @tracked placement = 'bottom-start';
+  @tracked distance = 6;
+  setPlacement = (v: string) => (this.placement = v);
+  setDistance = (v: number | null) => (this.distance = v ?? 6);
+  get placementVal() {
+    return this.placement as PopupPlacement;
+  }
+  get usage() {
+    return `<Popover @placement='${this.placement}' @distance={{${this.distance}}}>…</Popover>`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='Popover'
+      @description='This component is a building block for more complex components. It anchors a floating panel to its trigger with fixed positioning — flipping and shifting when out of room — and closes via backdrop click or Escape, so no #-in-element rendering or focus-trap addon is needed.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <Popover
+          @placement={{this.placementVal}}
+          @distance={{this.distance}}
+          @label='Demo popover'
+        >
+          <:trigger as |open toggle|>
+            <Button @tone='neutral' @appearance='outlined' {{on 'click' toggle}}>
+              {{if open 'Close' 'Trigger'}}
+            </Button>
+          </:trigger>
+          <:default as |close|>
+            <div class='pop-body'>
+              <p class='pop-copy'>A building block for more complex overlays —
+                anchored to its trigger, flipping when out of room.</p>
+              <Button @tone='primary' @size='s' {{on 'click' close}}>Done</Button>
+            </div>
+          </:default>
+        </Popover>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='placement'
+          @description='Preferred side and alignment of the panel relative to the trigger; flips to the opposite side when out of room.'
+          @value={{this.placement}}
+          @options={{PLACEMENT_OPTIONS}}
+          @defaultValue='bottom-start'
+          @onInput={{this.setPlacement}}
+        />
+        <Args.Number
+          @name='distance'
+          @description='Gap in pixels between the trigger and the panel.'
+          @value={{this.distance}}
+          @min={{0}}
+          @max={{24}}
+          @step={{1}}
+          @defaultValue='6'
+          @onInput={{this.setDistance}}
+        />
+        <Args.String
+          @name='label'
+          @description='Accessible label for the panel dialog.'
+          @defaultValue='Popover'
+          @hideControls={{true}}
+        />
+        <Args.Yield
+          @name='trigger'
+          @description='Content to be used as the trigger. Yields the open state and a toggle action — replaces the bindings modifier that applied aria- attributes and event handling.'
+          @hideControls={{true}}
+        />
+        <Args.Yield
+          @description='Content to show in the panel; rendered while open. Yields a close action to close the popover.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .pop-body {
+        display: grid;
+        gap: var(--space-3, 8px);
+        justify-items: start;
+      }
+      .pop-copy {
+        margin: 0;
+        font-size: var(--text-ui-md, 12.5px);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_POPOVER: Record<string, unknown> = {
+  Popover: PopoverUsage,
+};

package/bundled-realms/pretui/components/popup.gts

@@ -0,0 +1,85 @@
+// Pretui — Popup: an anchored floating layer, positioned by measuring on open.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { modifier } from 'ember-modifier';
+import { resolvePlacement, resolveOpen, anchorTo } from '../internal/overlay';
+import type { PopupPlacement, PlacementArgs, OpenArgs } from '../internal/overlay';
+
+export interface PopupSignature {
+  Args: OpenArgs &
+    PlacementArgs & {
+      placement?: PopupPlacement | string;
+      distance?: number;
+      matchWidth?: boolean;
+      /** Scale the floating panel with a zoomable host surface. Applied as a
+       * `transform`, clamped 0.4–2.5; 1 (the default) writes no transform. */
+      scale?: number;
+    };
+  Blocks: { anchor: []; default: [] };
+  Element: HTMLSpanElement;
+}
+
+/**
+ * Headless anchored-positioning primitive (wa-popup, trimmed). Renders its
+ * anchor inline and, while @open, a fixed-position container placed against
+ * it. Fixed positioning is intentional — anchored overlays must escape
+ * scroll clipping (lint warns; accepted, same as the Select backdrop).
+ */
+export class Popup extends Component<PopupSignature> {
+  @tracked anchorEl?: HTMLElement;
+  captureAnchor = modifier((el: HTMLElement) => {
+    this.anchorEl = el;
+  });
+  get placement(): PopupPlacement {
+    return resolvePlacement(this.args, 'bottom-start');
+  }
+  get open() {
+    return resolveOpen(this.args) ?? false;
+  }
+  get distance() {
+    return this.args.distance ?? 6;
+  }
+  get matchWidth() {
+    return this.args.matchWidth ?? false;
+  }
+  <template>
+    <span class='pretui-popup-anchor' {{this.captureAnchor}} ...attributes>
+      {{yield to='anchor'}}
+      {{#if this.open}}
+        <span
+          class='pretui-popup'
+          {{anchorTo
+            this.anchorEl
+            this.placement
+            this.distance
+            this.matchWidth
+            @scale
+          }}
+        >
+          {{yield}}
+        </span>
+      {{/if}}
+    </span>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-popup-anchor {
+          display: inline-block;
+        }
+        .pretui-popup {
+          /* anchored overlays must escape scroll clipping; measured on open
+             only — never during prerender (lint warns, accepted) */
+          position: fixed;
+          top: 0;
+          left: 0;
+          /* kit stacking scale (pretui-css.gts): `overlay` sits above
+             `dropdown` because a Popup can CONTAIN a Select or Menu, and a
+             containing panel must never paint under its own content.
+             Dialog/Drawer are not on the scale in practice — showModal()
+             promotes them to the top layer, above every z-index here. */
+          z-index: var(--pretui-z-overlay, 70);
+          display: block;
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/popup.md

@@ -0,0 +1,42 @@
+## What it is
+
+The kit's headless anchored-positioning primitive: render an anchor inline, and while `@open` is true render a fixed-position container placed against it with flip and shift applied. It has no chrome, no dismissal behaviour and no ARIA — it is the thing **Popover**, **Select**, **Lookup**, **Combobox** and **DatePicker** are built out of. Reach for it directly only when you are building a new anchored surface. If you want a floating panel a user opens and closes, use **Popover**; if you want a labelled hint on hover, use **Tooltip**; if you want a blocking surface, use **Dialog**.
+
+## The contract
+
+```
+@open?, @placement? (12 values, default 'bottom-start'), @distance? (default 6), @matchWidth? (default false)
+<:anchor> <:default>
+```
+
+`@placement` is the familiar `side` / `side-start` / `side-end` grid: `top|bottom|left|right` × `(none|-start|-end)`. `@matchWidth` sets the panel's `min-width` to the anchor's measured width — the behaviour a Select menu needs and a Tooltip must not have.
+
+Two decisions worth understanding.
+
+**`position: fixed`, and the panel is inside the anchor wrapper.** Anchored overlays have to escape scroll clipping, so the panel is `position: fixed` with computed `top`/`left`. The kit's lint warns about fixed positioning; it is accepted here for the same reason it is accepted on the Select backdrop. Crucially the panel still lives _inside_ the component's DOM subtree rather than being portaled — which keeps it inside the theme island, so scoped CSS and theme tokens apply without a portal-aware provider.
+
+**Positioning is a ~50-line modifier, not a library.** `anchorTo` measures the anchor's `DOMRect` and the panel's real box, flips to the opposite side when the preferred side lacks room and the opposite side has it, then clamps the cross-axis to an 8px viewport gutter. It re-runs on capture-phase `scroll` and on `resize`, and its teardown removes both listeners. Because it only ever runs while `@open` is true, it never executes during prerender — which is the constraint that ruled out the alternatives.
+
+## Prior art
+
+**floating-ui** is the reference implementation and what Radix, Web Awesome (`wa-popup`) and most of the ecosystem use: composable middleware (`offset`, `flip`, `shift`, `arrow`, `size`, `autoPlacement`, `hide`) with `autoUpdate` wiring `ResizeObserver` and ancestor scroll. **`wa-popup`** exposes `placement`, `distance`, `skidding`, `strategy`, `flip`, `shift`, `arrow`, `sync`, `auto-size`. **boxel-ui** uses ember-velcro, which portals to the application root.
+
+Pretui reimplements rather than adopts, for two hard reasons: floating-ui is not realm-importable, and boxel-ui's velcro path portals _outside_ the theme island, which breaks theming (the `renderInPlace` decision). Given that, the question is what to keep. Kept: offset (`@distance`), flip, shift, and `size`-style width matching. Dropped: `skidding` (cross-axis nudge), arrows, `autoPlacement`, `hide`, and `strategy` selection.
+
+The improvement over a naive reimplementation is that flip measures **the real panel box**, not an estimate — `apply()` reads `getBoundingClientRect()` after the panel is in the DOM, so a panel whose height depends on its content flips correctly on first paint rather than one frame late.
+
+The honest weakness versus floating-ui: no `ResizeObserver` and no `autoUpdate`. If the panel's own content changes size while open — an async list finishing loading — the position is stale until the next scroll or resize event. That is a real bug surface for anything that loads inside a popup.
+
+## Accessibility
+
+**None, by design.** `Popup` emits two `<span>`s and no roles, states or keyboard handling. It is a positioning primitive; the ARIA contract belongs to whatever builds on it. `Popover` adds `role="dialog"` and Escape; `Select` adds `role="listbox"`; `Combobox` adds `aria-activedescendant` and `aria-expanded`.
+
+If you use `Popup` directly you own all of it: labelling, `aria-expanded`/`aria-controls` on the trigger, focus movement, Escape, and dismissal. There is no light-dismiss here either — `Popup` will stay open forever unless you flip `@open`. Consider that a checklist, not a limitation.
+
+One structural note: because the panel is a descendant of the anchor wrapper rather than portalled, it inherits the anchor's stacking and accessibility context. Screen-reader reading order follows DOM order, which is usually what you want and is one place the no-portal choice is straightforwardly better than the ecosystem default.
+
+## Theming
+
+Almost nothing: `z-index: 60` and layout only. Every visual token belongs to the consumer's panel. Callers that need to re-layer overlays should note the kit's convention — 49/50 for Menu's backdrop and panel, 60 for `Popup` and `Tooltip`, and the native top layer (above everything) for `Dialog` and `Drawer`.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/popup.usage.gts

@@ -0,0 +1,23 @@
+// Pretui — Popup usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { FreestyleUsage } from './freestyle-usage';
+import { Button } from './button';
+import { Popup } from './popup';
+
+class PopupUsage extends Component {
+  @tracked open = false;
+  toggle = () => (this.open = !this.open);
+  <template>
+    <FreestyleUsage @name='Popup' @description='The headless anchored-positioning foundation used by higher-level overlays. It owns clipping escape and placement, not panel appearance or dismissal policy.' @source='<Popup @open={{this.open}} @placement="bottom-start">…</Popup>'>
+      <:example><Popup @open={{this.open}} @placement='bottom-start' @distance={{8}}><:anchor><Button @variant='secondary' {{on 'click' this.toggle}}>Toggle details</Button></:anchor><:default><div class='popup-panel'><b>Lot B-103</b><span>65 chests · Shizuoka</span><Button @variant='ghost' {{on 'click' this.toggle}}>Close</Button></div></:default></Popup></:example>
+      <:api as |Args|><Args.Bool @name='open' @value={{this.open}} @onInput={{this.toggle}} /><Args.String @name='placement' @value='bottom-start' /><Args.Number @name='distance' @value={{8}} /><Args.Bool @name='matchWidth' @defaultValue={{false}} /><Args.Yield @name='anchor' /><Args.Yield @name='default' /></:api>
+    </FreestyleUsage>
+    <style scoped>.popup-panel { display: grid; gap: 5px; min-width: 220px; padding: 10px; border-radius: var(--radius); color: var(--foreground); background: var(--popover); box-shadow: var(--pretui-shadow-raised); font-size: var(--text-ui-md); }.popup-panel > span { color: var(--muted-foreground); }</style>
+  </template>
+}
+
+export const DEMOS_POPUP: Record<string, unknown> = {
+  Popup: PopupUsage,
+};