overlay — wyrd.component.popover

Popover

Non-modal anchored overlay with a trigger slot, open state, dismissal, and collision-aware positioning.

Install @wyrd-company/react or the Flutter package and use it directly — your DESIGN.md does the styling.

catalog/contracts/popover.yml source of truth · verbatim

$schema: https://thewyrdingway.dev/schemas/component-contract.schema.ymlcontractVersion: 0.1.0identity:  name: Popover  tag: wyrd-popover  package: wyrd.component.popover  title: Popover  summary: Non-modal anchored overlay with a trigger slot, open state, dismissal, and collision-aware positioning.relationships:  related-to:    - quality-parity-and-gatesclassification:  category: overlay  composition: multi-slot  interactive: truetarget-strategy:  react: required  flutter: requiredsurface:  properties:    - name: is-open      type:        kind: boolean      required: false      default: false      controlled: true      reflects: true      serializable: true      summary: Controlled popover visibility.    - name: default-open      type:        kind: boolean      required: false      default: false      serializable: true      summary: Initial uncontrolled popover visibility.    - name: placement      type:        kind: enum        values:          - top          - bottom          - start          - end      required: false      default: bottom      reflects: true      serializable: true      summary: Preferred surface placement relative to the trigger.    - name: trigger-mode      type:        kind: enum        values:          - click          - hover      required: false      default: click      reflects: true      serializable: true      summary: Interaction that opens the popover; hover also supports keyboard focus.    - name: dismissible      type:        kind: boolean      required: false      default: true      reflects: true      serializable: true      summary: Allows Escape and outside pointer dismissal.  slots:    - name: trigger      required: true      cardinality: exactly-one      accepts:        - component      summary: Anchor component; clicking it toggles the popover.    - name: content      content: true      required: true      cardinality: one-or-many      accepts:        - component        - content        - node      summary: Popover surface content.  events:    - name: open-change      payload:        is-open:          kind: boolean        reason:          kind: enum          values:            - trigger            - hover            - focus            - escape            - outside-pointer            - programmatic      bubbles: true      composed: true      cancelable: false      summary: Canonical open-state change event.  states:    - name: closed      source: behavior-runtime      summary: Popover content is hidden.    - name: open      source: behavior-runtime      summary: Popover content is visible and anchored to the trigger.  parts:    - name: root      summary: Popover root and event owner.      slots:        - trigger        - content    - name: trigger      summary: Trigger wrapper.      slots:        - trigger    - name: surface      summary: Anchored popover surface.      slots:        - content  tokens:    surface:      background: color.surface-container      foreground: color.on-surface      border-color: color.outline    border-width: 1px    radius: rounded.md    shadow: shadow.md    padding-x: spacing.md    padding-y: spacing.md    offset: spacing.xsmessages: []obligations:  accessibility:    role: none    name: Popover surface has no required accessible name and therefore does not force role=dialog in v1.    keyboard:      - Escape closes the popover and restores focus to the trigger when dismissible is true.      - Hover trigger mode opens when keyboard focus enters the trigger and remains open while focus is within the trigger or popover content.    semantics:      - Popover is non-modal; it does not trap focus and does not make background content inert.      - Trigger exposes aria-expanded.      - Trigger exposes aria-controls.      - Focus moves into the popover only when it contains a focusable descendant.  behavior:    model: overlay    interactions:      - Trigger click toggles the popover.      - Hover trigger mode opens after a 200 ms pointer-hover delay and closes after a 100 ms pointer-leave delay.      - Hover trigger mode opens immediately when keyboard focus enters the trigger and closes when focus leaves both trigger and content.      - Moving the pointer from the trigger into the popover content cancels a pending close so interactive content remains usable.      - Escape closes the popover and restores focus to the trigger when dismissible is true.      - Outside pointer down closes the popover when dismissible is true.      - Positioning uses the package anchoring utility with fixed coordinates, flip, shift, and RTL-aware start/end placement.    hostEffects:      - Recompute fixed coordinates when the popover opens and while visible on capture-phase scroll and viewport resize.      - Anchor tracking during layout animations is not guaranteed in v1.  conditions:    - rtl    - reduced-motion    - cvd-deuteranopia    - density-compact    - text-expansion  sdui:    status: serializable    serializableProperties:      - is-open      - default-open      - placement      - trigger-mode      - dismissible    serializableSlots:      - trigger      - content    eventBindings:      - open-change    notes: Popover serializes trigger/content slots and open-state data. Web projections use collision-aware fixed positioning through the hand-written package positioning utility. The popover is non-modal; hosts must not infer focus trap or inert background behavior.examples:  - name: basic    state: closed    properties:      default-open: false      placement: bottom      trigger-mode: click    slots:      trigger: Details      content: Additional details for the selected item.  - name: open    state: open    properties:      default-open: true      placement: bottom    slots:      trigger: Details      content: Additional details for the selected item.  - name: hover-card    state: closed    properties:      trigger-mode: hover      placement: bottom    slots:      trigger: Profile      content: Profile details and actions.  - name: nondismissible    state: open    properties:      default-open: true      dismissible: false    slots:      trigger: Inspector      content: Persistent inspector controls.overrides:  react:    slots:      trigger: trigger      content: children  flutter:    slots:      content: child

Examples

Generated from the contract's examples block. Previews are the published @wyrd-company/react component, themed by the brand's role tokens — flip the site's light/dark toggle and they follow.

Code target React Flutter Applies to every example on component pages.

basic state: closed

Usage

import { WyrdPopover } from "@wyrd-company/react";

export function PopoverInteractionExample() {
  return <WyrdPopover placement="bottom" trigger={<button type="button">Details</button>}>
    Additional details for the selected item.
  </WyrdPopover>;
}

import 'package:flutter/widgets.dart';
import 'package:wyrd_flutter/wyrd_flutter.dart';

Widget popoverInteractionExample() => WyrdPopover(
  placement: WyrdPopoverPlacement.bottom,
  trigger: const WyrdButton(variant: WyrdButtonVariant.secondary, child: Text('Details')),
  child: const [Text('Additional details for the selected item.')],
);

open state: open

Usage

import { WyrdPopover } from "@wyrd-company/react";

<WyrdPopover defaultOpen placement="bottom" trigger="Details">
  Additional details for the selected item.
</WyrdPopover>

// events: onOpenChange

import 'package:wyrd_flutter/wyrd_flutter.dart';

WyrdPopover(
  defaultOpen: true,
  placement: 'bottom',
  trigger: Text('Details'),
  child: Text('Additional details for the selected item.'),
)

// events: onOpenChanged

hover-card state: closed

Usage

import { WyrdPopover } from "@wyrd-company/react";

<WyrdPopover triggerMode="hover" placement="bottom" trigger="Profile">
  Profile details and actions.
</WyrdPopover>

// events: onOpenChange

import 'package:wyrd_flutter/wyrd_flutter.dart';

WyrdPopover(
  triggerMode: 'hover',
  placement: 'bottom',
  trigger: Text('Profile'),
  child: Text('Profile details and actions.'),
)

// events: onOpenChanged

nondismissible state: open

Usage

import { WyrdPopover } from "@wyrd-company/react";

<WyrdPopover defaultOpen dismissible={false} trigger="Inspector">
  Persistent inspector controls.
</WyrdPopover>

// events: onOpenChange

import 'package:wyrd_flutter/wyrd_flutter.dart';

WyrdPopover(
  defaultOpen: true,
  dismissible: false,
  trigger: Text('Inspector'),
  child: Text('Persistent inspector controls.'),
)

// events: onOpenChanged

Properties

Name	Type	Default	Summary
`is-open`	`boolean`	`false`	Controlled popover visibility.
`default-open`	`boolean`	`false`	Initial uncontrolled popover visibility.
`placement`	`top \| bottom \| start \| end`	`bottom`	Preferred surface placement relative to the trigger.
`trigger-mode`	`click \| hover`	`click`	Interaction that opens the popover; hover also supports keyboard focus.
`dismissible`	`boolean`	`true`	Allows Escape and outside pointer dismissal.

Slots & events

Slot	Cardinality	Accepts	Summary
`trigger`	exactly-one	`component`	Anchor component; clicking it toggles the popover.
`content`	one-or-many	`component, content, node`	Popover surface content.

Event	Payload	Summary
`open-change`	`is-open, reason`	Canonical open-state change event.

Tokens

The contract's token bindings. Open the shared contextual sidebar from any example; primary swatches reflect the color you pick there. Error swatches show the active preset's values; editing any knob switches to custom and resets error to TWW · Ink.

Binding	Token
`surface.background`	`color.surface-container`
`surface.foreground`	`color.on-surface`
`surface.border-color`	`color.outline`
`border-width`	`1px`
`radius`	`rounded.md`
`shadow`	`shadow.md`
`padding-x`	`spacing.md`
`padding-y`	`spacing.md`
`offset`	`spacing.xs`

States

State	Source	Summary
`closed`	behavior-runtime	Popover content is hidden.
`open`	behavior-runtime	Popover content is visible and anchored to the trigger.

SDUI

Status: serializable. Popover serializes trigger/content slots and open-state data. Web projections use collision-aware fixed positioning through the hand-written package positioning utility. The popover is non-modal; hosts must not infer focus trap or inert background behavior.

Serializable	Members
Properties	`is-open, default-open, placement, trigger-mode, dismissible`
Slots	`trigger, content`
Events	`open-change`

  The Wyrding Way — a contract-first design system. © Wyrd Company 
   Pipeline demo
 Choose an example to inspect its pipeline context.
 Explore the shape of a brand's pipeline input: presets and knobs regenerate the illustrative excerpt below — not a compilable DESIGN.md (see the format reference). Primary swatches update live; accent, shape, density, and ground are excerpt-only; error swatches are preset-derived until any edit switches to custom (TWW · Ink errors). Component previews use the published brand package and the site's light/dark toggle.
 
  Start from
       
 * homages — shown for range, not affiliation.
 
  Tokens
 Primary updates live swatches. Accent, shape, density, and ground appear in the excerpt only. Error swatches follow the preset until you edit a knob — then they reset to TWW · Ink.
  color.primary   #26221A    color.accent   #9C7C14    rounded.md   2px    density   1.0×    ground     
 
   DESIGN.md excerpt illustrative

Examples

Properties

Slots & events

Tokens

States

Accessibility

SDUI