--- name: popover-usage description: > Use after component-usage-ux when an app needs @techsio/ui-kit Popover for anchored non-blocking content using Zag.js compound parts, placement, portalling, close behavior, arrow, title, description, and close trigger. metadata: component_version: "2.0.0" type: "core" library: "@techsio/ui-kit" library_version: "0.3.2" requires: "component-usage-ux zag-compound-components app-token-overrides ux-guidelines" resources: "references/ux.md ../../references/component-contracts.md ../../references/consumer_app_usage_rules.md" sources: "https://zagjs.com/components/react/popover" contributor_sources: "libs/ui/src/molecules/popover.tsx libs/ui/src/tokens/components/molecules/_popover.css libs/ui/stories/molecules/popover.stories.tsx libs/ui/src/molecules/popover.figma.ts" audience: "consumer" --- > Portable scope: Use the installed package's exported types and bundled sibling skills. Repository source paths are optional contributor evidence, not consumer prerequisites; use the consuming app's own checks. Resolve ../../references/ paths from this skill's folder, not the app working directory. # @techsio/ui-kit Popover Usage Use Popover for anchored, dismissible content. Use Dialog for modal flows and Tooltip for tiny supplemental text. ## UX/UI guidelines House rules come from the `ux-guidelines` skill (writing, formatting, states, where actions and feedback live). This section applies them to `Popover`. **Use it when** - Small interactive content anchored to its trigger: filter panels, colour pickers, quick edit of one value, share options. **Use something else when** | Need | Use instead | | --- | --- | | A decision that must block the page | Dialog | | A read-only hint | Tooltip | | A list of commands | Menu | | Large forms | Dialog / drawer | **Do** - Keep content short; if it scrolls, it should be a dialog. - End filter popovers with `[Reset] [Apply]` bottom-right, or apply instantly — not both. - Return focus to the trigger on close; close on Escape and outside click. **Don't** - Put required information only in a popover. - Open popovers on hover. **Copy and states** - Trigger text says what opens (`Filters`, `Share`); count active filters in the trigger (`Filters (2)`). **Behaviour (from the UX spec)** - Closing (Escape, outside click, close button) never applies a half-made change; an unapplied filter draft is discarded. - Without a visible title, give `Popover.Content` an `aria-label`; without a close button, Escape and outside click must still close it. - `placement` is a preference: the kit flips on collision (`flip` defaults to `true`). **Figma → code** | Figma | Code | | --- | --- | | `showArrow` | `` | | Popover/Content `showTitle`, `showDescription`, `showCloseButton` | the `Title`, `Description`, `CloseTrigger` parts | | Popover/Placement set `placement=…` | `placement` on the root (reference set, not a component) | Full UX page (anatomy, states, behaviour, edge cases): [references/ux.md](references/ux.md). The same page renders in Storybook as *Molecules/Popover → UX guidelines*. ## Setup ```tsx import { Popover } from "@techsio/ui-kit/molecules/popover" Filters Filters Refine results. ``` Supported root props: ```text size sm | md | lg, shadow, border placement, gutter, offset, flip, sameWidth, slide, overflowPadding open/defaultOpen, onOpenChange, modal, portalled closeOnEscape, closeOnInteractOutside, autoFocus ``` ## Core Patterns ### Keep positioner/content anatomy `Popover.Positioner` conditionally renders and portals content. Do not move Content outside the root. ### Use for non-blocking anchored content Filters, small menus with custom controls, and contextual panels fit Popover. Confirmations and forms that must trap focus should use Dialog. ### Use close trigger for explicit close `Popover.CloseTrigger` wires Zag close behavior and supplies a token close icon. ## Common Mistakes ### HIGH Custom positioned panel Wrong: ```tsx
``` Correct: ```tsx Open ``` Source: libs/ui/src/molecules/popover.tsx ### HIGH Dialog-worthy content in Popover Wrong: ```tsx ``` Correct: ```tsx {/* form */} ``` ### HIGH Inline panel visuals Wrong: ```tsx ``` Correct: ```tsx ``` Source: libs/ui/src/tokens/components/molecules/_popover.css ## Validation Commands ```sh rg -n "absolute.*top-full|]*className=.*(bg-|p-|rounded-|shadow-)" apps rg -U -P -n "