@wentools/overlay

Svelte 5 popover, dropdown menu, and tooltip components with CSS custom property theming.

Install

npm install @wentools/overlay

Peer dependencies: svelte >=5.0.0, @wentools/spatial >=0.2.0, @wentools/simmer >=0.1.0

Components

| Component | Description | | ---------------------- | -------------------------------------------------- | | Popover | Base positioned overlay (positioning only) | | ClickPopover | Click-triggered popover with toggle | | HoverPopover | Hover/focus-triggered tooltip with debounce | | DropdownMenu | Accessible menu with keyboard navigation | | AutocompletePopover | Input-based suggestions popover | | MenuItem | Menu item for DropdownMenu/AutocompletePopover | | MenuSeparator | Divider line between menu items |

Usage

<script>
  import { DropdownMenu, MenuItem, MenuSeparator } from '@wentools/overlay'
</script>

<DropdownMenu>
  {#snippet trigger({ toggle, open })}
    <button onclick={toggle}>Menu</button>
  {/snippet}

  {#snippet children({ close })}
    <MenuItem onclick={() => { doAction(); close(); }}>Action</MenuItem>
    <MenuSeparator />
    <MenuItem onclick={close}>Cancel</MenuItem>
  {/snippet}
</DropdownMenu>

CSS Custom Properties

All components use a three-tier CSS fallback pattern:

var(--popover-*, var(--design-system-*, hardcoded-fallback))

This means:

1. Library tokens (--popover-*) — set these to theme the library
2. Design system tokens (--color-bg-elevated, etc.) — automatically picked up if your app defines them
3. Hardcoded fallbacks — sensible defaults when nothing else is set

Token Reference

| Token | Fallback chain | Used by | | ---------------------------- | --------------------------------------------------- | -------------------------- | | --popover-z-index | --layer-tooltip → 1000 | Popover | | --popover-bg | --color-bg-elevated → #fff | Click, Hover, Dropdown, AC | | --popover-color | --color-text-primary → inherit | Hover | | --popover-border-width | --border-thickness-m → 1px | Click, Hover, Dropdown, AC | | --popover-border-color | --color-border-default → #e0e0e0 | Click, Hover, Dropdown, AC | | --popover-radius | --radius-m → 8px | Click, Dropdown, AC | | --popover-radius-sm | --radius-s → 6px | Hover, menu items | | --popover-padding | --space-xs → 4px | Hover, Dropdown, AC | | --popover-padding-lg | --space-s → 8px | Click, Hover, Dropdown, AC | | --popover-shadow | --shadow-layer-2 → 0 4px 12px rgba(0,0,0,0.12) | Click, Dropdown, AC | | --popover-shadow-sm | --shadow-layer-1 → 0 2px 8px rgba(0,0,0,0.08) | Hover | | --popover-item-hover-bg | --color-surface-hover → rgba(0,0,0,0.04) | Dropdown, AC | | --popover-separator-color | --color-border-subtle → #e0e0e0 | Dropdown, MenuSeparator |

Consumer Scenarios

No config needed — hardcoded fallbacks provide a clean default look.

Design system app — if your app already defines --color-bg-elevated, --radius-m, etc., the components pick them up automatically.

Custom theme — set --popover-* tokens on a parent element:

:root {
  --popover-bg: #1a1a2e;
  --popover-border-color: #333;
  --popover-radius: 12px;
  --popover-shadow: 0 8px 24px rgba(0,0,0,0.3);
}

License

MIT