# Popover

> A small card anchored to what you pointed at, with the facts you need about it and one or two ways to go further. The scene popover gives its length in eighths, its cast and its shooting day.

Source: https://kwark.space/designSystem/components/popover

## Usage

### What it is
A card that opens from a trigger and points back at it with a small notch. It holds a few facts and at most two ways to go further. It is non-modal: the page behind stays readable, and pressing anywhere else closes it.

### The Kwark idea: the scene's production facts at a glance
Scene references appear everywhere in Kwark: call sheet rows, breakdown notes, comments, the schedule. Press **12** on a call sheet and the scene popover gives what a production person needs before deciding whether to open it: the heading in Courier, the page and length in eighths (*26 · 2 4/8 pages*), the cast, the shooting day with its strip colour (*Day 7 of 24 · Thu 20 Nov*) and the location. Then *Open in the screenplay* or *Show on the stripboard*. The same pattern serves characters (*Mira Rao · Lead · 41 of 96 scenes*) and locations.

### When to use
- A few read-only facts about something referenced on the page.
- A small set of options tied to one item that do not fit a [menu](https://kwark.space/designSystem/components/menu.md), such as a colour for a strip.

### When not to use
- More than about six facts or any form with more than two fields: open a [drawer](https://kwark.space/designSystem/components/drawer.md) on desktop or a [sheet](https://kwark.space/designSystem/components/sheet.md) on a phone.
- For a name and shortcut on hover: a [tooltip](https://kwark.space/designSystem/components/tooltip.md).
- For commands only: a [menu](https://kwark.space/designSystem/components/menu.md).

### Opening
- Opens on press (and on Enter). On a desk it may also open after a 500ms hover over a scene reference, and then it stays while the pointer is over it.
- Places itself below the trigger and flips above when there is no room; the notch follows the trigger.
- On a phone it opens as a short [sheet](https://kwark.space/designSystem/components/sheet.md), never a floating card under a thumb.

## Style

### Anatomy

1. **Card**: up to 320px, 14px 16px 12px padding, `--k-surface`, 1px `--k-line`, 10px corners, `--k-shadow-pop` (it floats).
2. **Notch**: a 10px square turned 45°, sharing the card's line and ground, 6px out from the edge, aligned to the trigger's centre (`--kw-pop-x`).
3. **Head**: the scene number box (Courier Prime 700) and the heading (Courier Prime 700 12px, capitals), and a close button when it opened by press.
4. **Facts**: a two-column `<dl>`, 12px; terms in `--k-text-2`, values tabular; the shooting day carries a 10px strip swatch.
5. **Foot**: a 1px line, then one or two [text buttons](https://kwark.space/designSystem/components/text-button.md) at 12px.
6. **Trigger** (`kw-sceneref`): a 28px pill with the number in a small Courier box; lit with `--k-raise` while open.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-surface` | #ffffff | #1a1a1a |
| `--k-line` | #e2e8f0 | rgba(255, 255, 255, .1) |
| `--k-raise` | #f1f5f9 | #252525 |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-focus` | #0f172a | #f4f4f5 |
| `--k-shadow-pop` | 0 1px 2px rgba(15, 23, 42, .06), 0 12px 32px rgba(15, 23, 42, .12) | 0 2px 6px rgba(0, 0, 0, .2), 0 16px 36px rgba(0, 0, 0, .55) |
| `--k-strip-int-night` | #8fb4d6 |  |
| `--k-strip-ink` | #1f2427 |  |
| `--k-radius-card` | 10px |  |
| `--k-radius-pill` | 999px |  |
| `--k-font-screenplay` | 'Courier Prime', 'Courier New', monospace |  |
| `--k-fs-meta` | 12px |  |
| `--k-fs-dense` | 11px |  |

## Code

### React

Use the HTML below with `kwark.css`. The example shows the markup and styling. Supply any application behavior described on this page.

### HTML and CSS

Works anywhere with `kwark.css`.

```html
<div class="kw-pop-anchor">
  <button class="kw-sceneref" type="button" aria-expanded="true" aria-haspopup="dialog"><b>12</b>Edit suite</button>
  <div class="kw-pop" role="dialog" aria-label="Scene 12, INT. EDIT SUITE – NIGHT">
    <div class="kw-pop__head"><span class="kw-cmdk__scene">12</span><p class="kw-pop__slug">Int. Edit suite – night</p><button class="kw-icon-button kw-pop__close" type="button" aria-label="Close Scene 12 details"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M18 6 6 18M6 6l12 12"/></svg></button></div>
    <dl class="kw-pop__facts">
      <dt>Page</dt><dd>26 · 2 4/8 pages</dd>
      <dt>Cast</dt><dd>Mira, Aanya · Nana (V.O.)</dd>
      <dt>Shoots</dt><dd><i class="kw-pop__strip" style="--kw-strip:var(--k-strip-int-night)"></i>Day 7 of 24 · Thu 20 Nov</dd>
      <dt>Location</dt><dd>Studio 2, Andheri</dd>
    </dl>
    <div class="kw-pop__foot"><a class="kw-text-button" href="#scene-12"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M15.5 3H5a2 2 0 0 0-2 2v14c0 1.1.9 2 2 2h14a2 2 0 0 0 2-2V8.5L15.5 3Z"/><path d="M15 3v6h6"/></svg><span>Open in the screenplay</span></a><a class="kw-text-button" href="#strip-12"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3" y="3" width="18" height="18" rx="2"/><path d="M7 3v18M17 3v18M3 8h4M3 16h4M17 8h4M17 16h4"/></svg><span>Show on the stripboard</span></a></div>
  </div>
</div>
<div class="kw-pop-anchor">
  <div class="kw-pop kw-pop--above" role="dialog" aria-label="Mira Rao" style="--kw-pop-x:28px">
    <div class="kw-pop__head"><span class="kw-avatar" style="--kw-peer:var(--k-series-1)">MR</span><div><p class="kw-pop__slug" style="font-family:var(--k-font-ui);text-transform:none;font-weight:600">Mira Rao</p><p class="kw-meta" style="margin:0">Lead · played by Tara Sen</p></div></div>
    <dl class="kw-pop__facts"><dt>Scenes</dt><dd>41 of 96 · first in Scene 2</dd><dt>Days</dt><dd>18 of 24</dd></dl>
  </div>
  <button class="kw-sceneref" type="button" aria-expanded="true" aria-haspopup="dialog"><b>MR</b>Mira</button>
</div>
<div class="kw-pop-anchor"><button class="kw-sceneref" type="button" aria-expanded="false" aria-haspopup="dialog"><b>14</b>Omitted</button></div>
```

## Accessibility

### Keyboard
| Key | Does |
|---|---|
| Enter / Space on the trigger | Opens; focus moves to the first link in the popover (or the close button). |
| Tab | Moves through the popover's links, then leaves it and closes it. |
| Escape | Closes and returns focus to the trigger. |

### ARIA
- The trigger has `aria-haspopup="dialog"` and `aria-expanded`; the card is a non-modal `role="dialog"` named for the thing (*Scene 12, INT. EDIT SUITE – NIGHT*).
- A hover-opened popover does not move focus, stays while hovered, and closes on Escape (WCAG 1.4.13).
- The strip swatch is decorative; the day is in words.

## For agents

### Rules

- **Must** be anchored to its trigger with a notch, and return focus to that trigger on Escape.
- **Never** put a form of more than two fields in a popover; use a drawer or a sheet.
- **Always** give scene popovers the page and length in eighths, the cast and the shooting day in words.
- **Must** open as a sheet on phones.
- **Never** cover the text that the popover is about; flip above or to the side instead.

### AI readiness test

**Task:** Show scene details when someone presses a scene number on the Day 7 call sheet.

**Give the agent:** This page, Call sheet, Stripboard strip.

**Constraint:** Some crew have Read access only to the screenplay.

**A reliable answer:**
- Anchored popover with Courier number and heading, page and eighths, cast and shooting day
- "Open in the screenplay" read-only for those with Read access
- Escape returns to the number
- A sheet on phones
