@wentools/overlay 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wentools
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+# @wentools/overlay
+
+Svelte 5 popover, dropdown menu, and tooltip components with CSS custom property theming.
+
+## Install
+
+```bash
+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
+
+```svelte
+<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:
+
+```css
+:root {
+  --popover-bg: #1a1a2e;
+  --popover-border-color: #333;
+  --popover-radius: 12px;
+  --popover-shadow: 0 8px 24px rgba(0,0,0,0.3);
+}
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@wentools/overlay",
+  "version": "0.1.0",
+  "description": "Svelte 5 popover, dropdown menu, and tooltip components with CSS custom property theming",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/wentools/overlay"
+  },
+  "keywords": [
+    "svelte",
+    "popover",
+    "dropdown",
+    "menu",
+    "tooltip",
+    "overlay",
+    "typescript"
+  ],
+  "type": "module",
+  "svelte": "./src/mod.ts",
+  "exports": {
+    ".": {
+      "svelte": "./src/mod.ts",
+      "types": "./src/mod.ts",
+      "default": "./src/mod.ts"
+    }
+  },
+  "peerDependencies": {
+    "svelte": ">=5.0.0",
+    "@wentools/spatial": ">=0.1.0",
+    "@wentools/simmer": ">=0.1.0"
+  }
+}

package/src/autocomplete_popover.svelte

@@ -0,0 +1,187 @@
+<!--
+@component
+AutocompletePopover - A popover for input-based suggestions
+
+Provides positioned suggestions below an input field with keyboard navigation support.
+The input remains the primary focus while suggestions enhance the experience.
+
+Perfect for: search autocomplete, tag pickers, user selectors, command palettes.
+
+@example
+```svelte
+<AutocompletePopover
+  open={showSuggestions}
+  onNavigate={handleNavigate}
+  onSelect={handleSelect}
+>
+  {#snippet input()}
+    <TextInput bind:value={searchTerm} />
+  {/snippet}
+
+  {#snippet suggestions()}
+    {#each results as item}
+      <MenuItem onclick={() => selectItem(item)}>
+        {item.name}
+      </MenuItem>
+    {/each}
+  {/snippet}
+</AutocompletePopover>
+```
+-->
+<script lang="ts">
+	import type { Snippet } from 'svelte'
+	import Popover from './popover.svelte'
+	import type { Position } from './types'
+
+	/**
+	 * AutocompletePopover component props
+	 */
+	interface Props {
+		/** Whether the suggestions popover is open */
+		open?: boolean
+		/** Position of the popover relative to input */
+		position?: Position
+		/** Offset from the input element in pixels */
+		offset?: number
+		/** Maximum width of suggestions content (scales with typography) */
+		maxWidth?: string
+		/** Minimum width of suggestions content (scales with typography) */
+		minWidth?: string
+		/** Maximum height of suggestions content (scales with typography) */
+		maxHeight?: string
+		/** CSS class for styling the popover */
+		class?: string
+		/** Display type for trigger wrapper - useful for flex layouts */
+		triggerDisplay?: 'inline-block' | 'block' | 'flex' | 'inline-flex'
+		/** Whether to close on click outside (default true) */
+		closeOnClickOutside?: boolean
+		/** Whether to close on escape key (default true) */
+		closeOnEscape?: boolean
+		/** Callback when open state changes */
+		onOpenChange?: (open: boolean) => void
+		/** Callback when user navigates with arrow keys */
+		onNavigate?: (direction: 'up' | 'down', event: KeyboardEvent) => void
+		/** Callback when user presses enter to select */
+		onSelect?: (event: KeyboardEvent) => void
+		/** Input element that triggers the suggestions */
+		input: Snippet
+		/** Suggestions content - typically MenuItem components */
+		suggestions: Snippet<[{ close: () => void }]>
+	}
+
+	let {
+		open = $bindable(false),
+		position = 'bottom-start',
+		offset = 4,
+		maxWidth = '60ch',
+		minWidth = '30ch',
+		maxHeight = '20ch',
+		class: className = '',
+		triggerDisplay = 'inline-block',
+		closeOnClickOutside = true,
+		closeOnEscape = true,
+		onOpenChange,
+		onNavigate,
+		onSelect,
+		input,
+		suggestions,
+	}: Props = $props()
+
+	let inputContainer: HTMLElement | undefined
+
+	const close = () => {
+		open = false
+		onOpenChange?.(false)
+	}
+
+	const handleKeydown = (event: KeyboardEvent) => {
+		if (!open) return
+
+		switch (event.key) {
+			case 'ArrowDown':
+				event.preventDefault()
+				onNavigate?.('down', event)
+				break
+			case 'ArrowUp':
+				event.preventDefault()
+				onNavigate?.('up', event)
+				break
+			case 'Enter':
+				if (open) {
+					event.preventDefault()
+					onSelect?.(event)
+				}
+				break
+			case 'Escape':
+				if (open && closeOnEscape) {
+					event.preventDefault()
+					close()
+				}
+				break
+		}
+	}
+
+	// Listen for keydown events on the input container
+	$effect(() => {
+		if (!inputContainer) return
+
+		inputContainer.addEventListener('keydown', handleKeydown)
+		return () => {
+			inputContainer?.removeEventListener('keydown', handleKeydown)
+		}
+	})
+</script>
+
+<Popover
+	bind:open
+	{position}
+	{offset}
+	{triggerDisplay}
+	{closeOnClickOutside}
+	{closeOnEscape}
+	onOpenChange={(newOpen) => {
+		open = newOpen
+		onOpenChange?.(newOpen)
+	}}
+	role="combobox"
+	ariaLabel="Autocomplete suggestions"
+	class="autocomplete-popover {className}"
+>
+	{#snippet trigger()}
+		<div bind:this={inputContainer} class="autocomplete-input">
+			{@render input()}
+		</div>
+	{/snippet}
+
+	{#snippet content({ close })}
+		<div
+			class="autocomplete-suggestions"
+			style:max-width={maxWidth}
+			style:min-width={minWidth}
+			style:max-height={maxHeight}
+		>
+			{@render suggestions({ close })}
+		</div>
+	{/snippet}
+</Popover>
+
+<style>
+	.autocomplete-input {
+		/* Ensure input container is inline-block for proper positioning */
+		display: inline-block;
+		width: 100%;
+	}
+
+	.autocomplete-suggestions {
+		--menu-item-padding: var(--popover-padding, var(--space-xs, 4px)) var(--popover-padding-lg, var(--space-s, 8px));
+		--menu-item-hover-bg: var(--popover-item-hover-bg, var(--color-surface-hover, rgba(0,0,0,0.04)));
+		--menu-item-border-radius: var(--popover-radius-sm, var(--radius-s, 6px));
+
+		background: var(--popover-bg, var(--color-bg-elevated, #fff));
+		border: var(--popover-border-width, var(--border-thickness-m, 1px)) solid var(--popover-border-color, var(--color-border-default, #e0e0e0));
+		border-radius: var(--popover-radius, var(--radius-m, 8px));
+		padding: var(--popover-padding, var(--space-xs, 4px));
+		box-shadow: var(--popover-shadow, var(--shadow-layer-2, 0 4px 12px rgba(0,0,0,0.12)));
+		overflow-y: auto;
+	}
+</style>

package/src/click_popover.svelte

@@ -0,0 +1,127 @@
+<!--
+@component
+ClickPopover - Click-triggered popover component
+
+Provides a popover that opens/closes when the trigger is clicked.
+Handles focus management and provides toggle functionality.
+
+Perfect for: action menus, info popovers, quick settings panels.
+
+@example
+```svelte
+<ClickPopover>
+  {#snippet children({ toggle, open })}
+    <button onclick={toggle}>
+      Options {open ? '▼' : '▶'}
+    </button>
+  {/snippet}
+
+  {#snippet content({ close })}
+    <div>
+      <button onclick={close}>Action 1</button>
+      <button onclick={close}>Action 2</button>
+    </div>
+  {/snippet}
+</ClickPopover>
+```
+-->
+<script lang="ts">
+	import type { Snippet } from 'svelte'
+	import Popover from './popover.svelte'
+	import type { Position } from './types'
+
+	interface Props {
+		/** Position of the popover */
+		position?: Position
+		/** Offset from trigger element */
+		offset?: number
+		/** Maximum width of popover content */
+		maxWidth?: string
+		/** CSS class for styling the popover */
+		class?: string
+		/** Whether the popover is disabled */
+		disabled?: boolean
+		/** Whether to close on click outside (default true) */
+		closeOnClickOutside?: boolean
+		/** Whether to close on escape key (default true) */
+		closeOnEscape?: boolean
+		/** Callback when open state changes */
+		onOpenChange?: (open: boolean) => void
+		/** Trigger element (what you click) */
+		children: Snippet<[{ toggle: () => void; open: boolean }]>
+		/** Popover content */
+		content: Snippet<[{ close: () => void; open: boolean }]>
+	}
+
+	let {
+		position = 'bottom-start',
+		offset = 4,
+		maxWidth = '50ch',
+		class: className = '',
+		disabled = false,
+		closeOnClickOutside = true,
+		closeOnEscape = true,
+		onOpenChange,
+		children,
+		content: _content,
+	}: Props = $props()
+
+	let open = $state(false)
+
+	const toggle = () => {
+		if (disabled) return
+		open = !open
+		onOpenChange?.(open)
+	}
+
+	const close = () => {
+		open = false
+		onOpenChange?.(false)
+	}
+</script>
+
+<Popover
+	bind:open
+	{position}
+	{offset}
+	{closeOnClickOutside}
+	{closeOnEscape}
+	onOpenChange={(newOpen) => {
+		open = newOpen
+		onOpenChange?.(newOpen)
+	}}
+	class="click-popover {className}"
+>
+	{#snippet trigger()}
+		<div
+			onclick={toggle}
+			onkeydown={(e) => {
+				if (e.key === 'Enter' || e.key === ' ') {
+					e.preventDefault()
+					toggle()
+				}
+			}}
+			tabindex="0"
+			role="button"
+			aria-expanded={open}
+		>
+			{@render children({ toggle, open })}
+		</div>
+	{/snippet}
+
+	{#snippet content()}
+		<div class="click-popover-content" style:max-width={maxWidth}>
+			{@render _content({ close, open })}
+		</div>
+	{/snippet}
+</Popover>
+
+<style>
+	.click-popover-content {
+		background: var(--popover-bg, var(--color-bg-elevated, #fff));
+		border: var(--popover-border-width, var(--border-thickness-m, 1px)) solid var(--popover-border-color, var(--color-border-default, #e0e0e0));
+		border-radius: var(--popover-radius, var(--radius-m, 8px));
+		padding: var(--popover-padding-lg, var(--space-s, 8px));
+		box-shadow: var(--popover-shadow, var(--shadow-layer-2, 0 4px 12px rgba(0,0,0,0.12)));
+	}
+</style>

package/src/dropdown_menu.svelte

@@ -0,0 +1,226 @@
+<!--
+@component
+DropdownMenu - Accessible dropdown menu with keyboard navigation
+
+Provides a click-triggered menu with full keyboard navigation (arrow keys, home/end, enter).
+Follows ARIA menu patterns and manages focus automatically.
+
+Perfect for: context menus, action menus, navigation dropdowns.
+
+@example
+```svelte
+<DropdownMenu>
+  {#snippet trigger({ toggle, open })}
+    <button onclick={toggle}>
+      Menu {open ? '▼' : '▶'}
+    </button>
+  {/snippet}
+
+  {#snippet children({ close })}
+    <MenuItem onclick={() => { action1(); close(); }}>
+      Action 1
+    </MenuItem>
+    <MenuItem onclick={() => { action2(); close(); }}>
+      Action 2
+    </MenuItem>
+  {/snippet}
+</DropdownMenu>
+```
+-->
+<script lang="ts">
+	import type { Snippet } from 'svelte'
+	import Popover from './popover.svelte'
+	import type { Position } from './types'
+
+	interface Props {
+		/** Position of the dropdown */
+		position?: Position
+		/** Offset from trigger element */
+		offset?: number
+		/** Maximum width of dropdown content */
+		maxWidth?: string
+		/** CSS class for styling the dropdown */
+		class?: string
+		/** Whether the dropdown is disabled */
+		disabled?: boolean
+		/** Index of item to focus when opening. Defaults to 0 (first item). */
+		initialFocusIndex?: number
+		/** Callback when open state changes */
+		onOpenChange?: (open: boolean) => void
+		/** Trigger element (what you click) */
+		trigger: Snippet<[{ toggle: () => void; open: boolean }]>
+		/** Dropdown content - should contain MenuItem components */
+		children: Snippet<[{ close: () => void; open: boolean }]>
+	}
+
+	let {
+		position = 'bottom-start',
+		offset = 4,
+		maxWidth = '60ch',
+		class: className = '',
+		disabled = false,
+		initialFocusIndex = 0,
+		onOpenChange,
+		trigger: triggerSnippet,
+		children,
+	}: Props = $props()
+
+	let open = $state(false)
+	let menuElement: HTMLElement | undefined = undefined
+	let focusedIndex = $state(-1)
+
+	const toggle = () => {
+		if (disabled) return
+		open = !open
+		onOpenChange?.(open)
+
+		if (open) {
+			// Focus specified item when opening (defaults to first item)
+			focusedIndex = initialFocusIndex
+			setTimeout(() => focusItem(initialFocusIndex), 0)
+		} else {
+			focusedIndex = -1
+		}
+	}
+
+	const close = () => {
+		open = false
+		onOpenChange?.(false)
+		focusedIndex = -1
+	}
+
+	const getMenuItems = (): HTMLElement[] => {
+		if (!menuElement) return []
+		return Array.from(menuElement.querySelectorAll('[role="menuitem"]:not([disabled])'))
+	}
+
+	const focusItem = (index: number) => {
+		const items = getMenuItems()
+		if (items[index]) {
+			items[index].focus()
+			focusedIndex = index
+		}
+	}
+
+	const handleKeydown = (event: KeyboardEvent) => {
+		if (!open) return
+
+		const items = getMenuItems()
+		const currentIndex = focusedIndex
+
+		switch (event.key) {
+			case 'ArrowDown': {
+				event.preventDefault()
+				const nextIndex = currentIndex < items.length - 1 ? currentIndex + 1 : 0
+				focusItem(nextIndex)
+				break
+			}
+
+			case 'ArrowUp': {
+				event.preventDefault()
+				const prevIndex = currentIndex > 0 ? currentIndex - 1 : items.length - 1
+				focusItem(prevIndex)
+				break
+			}
+
+			case 'Home':
+				event.preventDefault()
+				focusItem(0)
+				break
+
+			case 'End':
+				event.preventDefault()
+				focusItem(items.length - 1)
+				break
+
+			case 'Enter':
+			case ' ':
+				event.preventDefault()
+				if (items[currentIndex]) {
+					items[currentIndex].click()
+				}
+				break
+
+			case 'Escape':
+				event.preventDefault()
+				close()
+				break
+		}
+	}
+
+	// Handle when menu items get focus (via mouse or keyboard)
+	const handleItemFocus = (event: FocusEvent) => {
+		const items = getMenuItems()
+		const focusedItem = event.target as HTMLElement
+		const index = items.indexOf(focusedItem)
+		if (index !== -1) {
+			focusedIndex = index
+		}
+	}
+</script>
+
+<svelte:window onkeydown={handleKeydown} />
+
+<Popover
+	bind:open
+	{position}
+	{offset}
+	closeOnClickOutside={true}
+	closeOnEscape={true}
+	onOpenChange={(newOpen) => {
+		open = newOpen
+		onOpenChange?.(newOpen)
+		if (!newOpen) {
+			focusedIndex = -1
+		}
+	}}
+	role="menu"
+	ariaLabel="Menu"
+	class="dropdown-menu {className}"
+>
+	{#snippet trigger()}
+		<div
+			onclick={toggle}
+			onkeydown={(e) => {
+				if (e.key === 'Enter' || e.key === ' ') {
+					e.preventDefault()
+					toggle()
+				}
+			}}
+			tabindex="0"
+			role="button"
+			aria-haspopup="menu"
+			aria-expanded={open}
+		>
+			{@render triggerSnippet({ toggle, open })}
+		</div>
+	{/snippet}
+
+	{#snippet content()}
+		<div
+			bind:this={menuElement}
+			class="dropdown-menu-content"
+			style:max-width={maxWidth}
+			role="menu"
+			onfocus={handleItemFocus}
+		>
+			{@render children({ close, open })}
+		</div>
+	{/snippet}
+</Popover>
+
+<style>
+	.dropdown-menu-content {
+		--menu-item-padding: var(--popover-padding, var(--space-xs, 4px)) var(--popover-padding-lg, var(--space-s, 8px));
+		--menu-item-hover-bg: var(--popover-item-hover-bg, var(--color-surface-hover, rgba(0,0,0,0.04)));
+		--menu-item-border-radius: var(--popover-radius-sm, var(--radius-s, 6px));
+		--menu-separator-color: var(--popover-separator-color, var(--color-border-subtle, #e0e0e0));
+
+		background: var(--popover-bg, var(--color-bg-elevated, #fff));
+		border: var(--popover-border-width, var(--border-thickness-m, 1px)) solid var(--popover-border-color, var(--color-border-default, #e0e0e0));
+		border-radius: var(--popover-radius, var(--radius-m, 8px));
+		padding: var(--popover-padding, var(--space-xs, 4px));
+		box-shadow: var(--popover-shadow, var(--shadow-layer-2, 0 4px 12px rgba(0,0,0,0.12)));
+		min-width: fit-content;
+	}
+</style>

package/src/hover_popover.svelte

@@ -0,0 +1,113 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte'
+	import Popover from './popover.svelte'
+	import { debounce } from '@wentools/simmer'
+	import type { Position } from './types'
+
+	interface Props {
+		/** Delay before showing in milliseconds */
+		showDelay?: number
+		/** Delay before hiding in milliseconds */
+		hideDelay?: number
+		/** Position of the popover */
+		position?: Position
+		/** Offset from trigger element */
+		offset?: number
+		/** Maximum width of tooltip content */
+		maxWidth?: string
+		/** CSS class for styling the popover */
+		class?: string
+		/** Whether the popover is disabled */
+		disabled?: boolean
+		/** Trigger element (what you hover over) */
+		children: Snippet
+		/** Popover content */
+		content: Snippet<[{ close: () => void; open: boolean }]>
+	}
+
+	let {
+		showDelay = 400,
+		hideDelay = 200,
+		position = 'top',
+		offset = 8,
+		maxWidth = '35ch',
+		class: className = '',
+		disabled = false,
+		children,
+		content: _content,
+	}: Props = $props()
+
+	let open = $state(false)
+	let isHovering = $state(false)
+
+	const debouncedShow = $derived(
+		debounce(() => {
+			if (isHovering && !disabled) {
+				open = true
+			}
+		}, showDelay),
+	)
+
+	const debouncedHide = $derived(
+		debounce(() => {
+			if (!isHovering) {
+				open = false
+			}
+		}, hideDelay),
+	)
+
+	const handleMouseEnter = () => {
+		isHovering = true
+		debouncedShow()
+	}
+
+	const handleMouseLeave = () => {
+		isHovering = false
+		debouncedHide()
+	}
+</script>
+
+<Popover
+	bind:open
+	{position}
+	{offset}
+	closeOnClickOutside={false}
+	closeOnEscape={false}
+	role="tooltip"
+	class="hover-popover {className}"
+>
+	{#snippet trigger()}
+		<div
+			onmouseenter={handleMouseEnter}
+			onmouseleave={handleMouseLeave}
+			onfocus={handleMouseEnter}
+			onblur={handleMouseLeave}
+			role="group"
+		>
+			{@render children()}
+		</div>
+	{/snippet}
+
+	{#snippet content({ close })}
+		<div
+			class="hover-popover-content"
+			onmouseenter={handleMouseEnter}
+			onmouseleave={handleMouseLeave}
+			style:max-width={maxWidth}
+			role="presentation"
+		>
+			{@render _content({ close, open })}
+		</div>
+	{/snippet}
+</Popover>
+
+<style>
+	.hover-popover-content {
+		background: var(--popover-bg, var(--color-bg-elevated, #fff));
+		color: var(--popover-color, var(--color-text-primary, inherit));
+		border: var(--popover-border-width, var(--border-thickness-m, 1px)) solid var(--popover-border-color, var(--color-border-default, #e0e0e0));
+		padding: var(--popover-padding, var(--space-xs, 4px)) var(--popover-padding-lg, var(--space-s, 8px));
+		border-radius: var(--popover-radius-sm, var(--radius-s, 6px));
+		box-shadow: var(--popover-shadow-sm, var(--shadow-layer-1, 0 2px 8px rgba(0,0,0,0.08)));
+	}
+</style>

package/src/menu_item.svelte

@@ -0,0 +1,102 @@
+<!--
+@component
+MenuItem - Individual menu item for DropdownMenu
+
+A styled menu item that works with DropdownMenu's keyboard navigation.
+Follows ARIA menuitem patterns and integrates with focus management.
+
+Perfect for: actions in dropdown menus, selectable options.
+
+@example
+```svelte
+<MenuItem onclick={() => handleAction()}>
+  Delete Item
+</MenuItem>
+
+<MenuItem disabled>
+  Unavailable Action
+</MenuItem>
+```
+-->
+<script lang="ts">
+	import type { Snippet } from 'svelte'
+
+	interface Props {
+		/** Whether the menu item is disabled */
+		disabled?: boolean
+		/** Whether the menu item is highlighted (keyboard navigation) */
+		highlighted?: boolean
+		/** Color theme for special items (e.g., 'var(--blue-ch)' for create, 'var(--red-ch)' for destructive) */
+		color?: string
+		/** Click handler */
+		onclick?: () => void
+		/** CSS class for styling */
+		class?: string
+		/** Menu item content */
+		children: Snippet
+	}
+
+	let {
+		disabled = false,
+		highlighted = false,
+		color,
+		onclick,
+		class: className = '',
+		children,
+	}: Props = $props()
+</script>
+
+<button
+	class="menu-item {className}"
+	class:highlighted
+	class:disabled
+	{disabled}
+	role="menuitem"
+	tabindex="-1"
+	style:--item-color={color}
+	onclick={() => {
+		if (!disabled) {
+			onclick?.()
+		}
+	}}
+>
+	{@render children()}
+</button>
+
+<style>
+	.menu-item {
+		/* Use CSS custom properties set by parent DropdownMenu */
+		padding: var(--menu-item-padding, var(--space-xs, 4px) var(--space-s, 8px));
+		border-radius: var(--menu-item-border-radius, var(--radius-s, 6px));
+
+		/* Base styling */
+		display: block;
+		width: 100%;
+		border: none;
+		background: none;
+		text-align: left;
+		cursor: pointer;
+		color: inherit;
+		transition: background-color 0.2s ease;
+	}
+
+	/* Default hover/focus states */
+	.menu-item:hover,
+	.menu-item:focus,
+	.menu-item.highlighted {
+		background: var(--menu-item-hover-bg, var(--color-surface-hover, rgba(0,0,0,0.04)));
+		outline: none;
+	}
+
+	/* Disabled states */
+	.menu-item.disabled {
+		opacity: 0.5;
+		cursor: not-allowed;
+	}
+
+	.menu-item.disabled:hover,
+	.menu-item.disabled:focus,
+	.menu-item.disabled.highlighted {
+		background: none;
+	}
+</style>

package/src/menu_separator.svelte

@@ -0,0 +1,27 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte'
+
+	interface Props {
+		/** Custom separator content. Defaults to a simple horizontal line. */
+		children?: Snippet
+	}
+
+	let { children }: Props = $props()
+</script>
+
+{#if children}
+	<div class="menu-separator" role="separator">
+		{@render children()}
+	</div>
+{:else}
+	<hr class="menu-separator" />
+{/if}
+
+<style>
+	.menu-separator {
+		border: none;
+		height: 1px;
+		background: var(--popover-separator-color, var(--color-border-subtle, #e0e0e0));
+		margin: var(--popover-padding, var(--space-xs, 4px)) 0;
+	}
+</style>

package/src/mod.ts

@@ -0,0 +1,8 @@
+export { default as Popover } from './popover.svelte'
+export { default as HoverPopover } from './hover_popover.svelte'
+export { default as ClickPopover } from './click_popover.svelte'
+export { default as AutocompletePopover } from './autocomplete_popover.svelte'
+export { default as DropdownMenu } from './dropdown_menu.svelte'
+export { default as MenuItem } from './menu_item.svelte'
+export { default as MenuSeparator } from './menu_separator.svelte'
+export type { Position } from './types'

package/src/popover.svelte

@@ -0,0 +1,317 @@
+<!--
+@component
+Popover - Base positioned overlay component
+
+Low-level popover that provides positioning, outside click handling, and escape key support.
+Use higher-level components like ClickPopover, DropdownMenu, or AutocompletePopover unless you need custom behavior.
+
+Perfect for: building custom popover patterns, tooltips, custom dropdowns.
+
+@example
+```svelte
+<Popover bind:open position="bottom-start">
+  {#snippet trigger()}
+    <button>Click me</button>
+  {/snippet}
+
+  {#snippet content({ close })}
+    <div>Custom popover content</div>
+  {/snippet}
+</Popover>
+```
+-->
+<script lang="ts">
+	import { onMount, tick } from 'svelte'
+	import type { Snippet } from 'svelte'
+	import type { Position } from './types'
+	import { centerHorizontally, centerVertically } from '@wentools/spatial'
+
+	interface Props {
+		/** Whether the popover is open */
+		open?: boolean
+		/** Position of the popover relative to trigger */
+		position?: Position
+		/** Offset from the trigger element in pixels */
+		offset?: number
+		/** Minimum distance from viewport edge in pixels */
+		viewportMargin?: number
+		/** Whether to close on click outside */
+		closeOnClickOutside?: boolean
+		/** Whether to close on escape key */
+		closeOnEscape?: boolean
+		/** ARIA role for accessibility */
+		role?: string
+		/** ARIA label for accessibility */
+		ariaLabel?: string
+		/** CSS class for the popover content */
+		class?: string
+		/** Display type for trigger wrapper - useful for flex layouts */
+		triggerDisplay?: 'inline-block' | 'block' | 'flex' | 'inline-flex' | 'contents'
+		/** Flex value for trigger wrapper when in flex container */
+		triggerFlex?: string
+		/** Callback when open state changes */
+		onOpenChange?: (open: boolean) => void
+		/** Trigger element */
+		trigger: Snippet
+		/** Popover content */
+		content: Snippet<[{ close: () => void }]>
+	}
+
+	let {
+		open = $bindable(false),
+		position = 'auto',
+		offset = 8,
+		viewportMargin = 0,
+		closeOnClickOutside = true,
+		closeOnEscape = true,
+		role,
+		ariaLabel,
+		class: className = '',
+		triggerDisplay = 'inline-block',
+		triggerFlex,
+		onOpenChange,
+		trigger,
+		content,
+	}: Props = $props()
+
+	// DOM element references (don't need $state)
+	let triggerElement: HTMLElement | undefined = undefined
+	let popoverElement: HTMLElement | undefined = $state(undefined)
+
+	// Reactive state for positioning
+	let positionX = $state(0)
+	let positionY = $state(0)
+	let actualPosition = $state<Position>(position)
+
+	const close = () => {
+		open = false
+		onOpenChange?.(false)
+	}
+
+	const calculatePosition = () => {
+		if (!triggerElement || !popoverElement) return
+
+		const triggerRect = triggerElement.getBoundingClientRect()
+		const popoverRect = popoverElement.getBoundingClientRect()
+		const viewport = {
+			width: window.innerWidth,
+			height: window.innerHeight,
+		}
+
+		let newX = 0
+		let newY = 0
+		let newPosition = position
+
+		// Helper function to check if a position fits
+		const canFit = (pos: Position): boolean => {
+			switch (pos) {
+				case 'top':
+				case 'top-start':
+				case 'top-end':
+					return triggerRect.top - offset - popoverRect.height >= viewportMargin
+				case 'bottom':
+				case 'bottom-start':
+				case 'bottom-end':
+					return (
+						triggerRect.bottom + offset + popoverRect.height <= viewport.height - viewportMargin
+					)
+				case 'left':
+				case 'left-start':
+				case 'left-end':
+					return triggerRect.left - offset - popoverRect.width >= viewportMargin
+				case 'right':
+				case 'right-start':
+				case 'right-end':
+					return triggerRect.right + offset + popoverRect.width <= viewport.width - viewportMargin
+				default:
+					return false
+			}
+		}
+
+		// Smart positioning with fallbacks
+		if (position === 'auto') {
+			// Preferred order: bottom, top, right, left (with all variants)
+			const positions: Position[] = [
+				'bottom',
+				'bottom-start',
+				'bottom-end',
+				'top',
+				'top-start',
+				'top-end',
+				'right',
+				'right-start',
+				'right-end',
+				'left',
+				'left-start',
+				'left-end',
+			]
+
+			newPosition = positions.find((pos) => canFit(pos)) ?? 'bottom'
+		} else {
+			newPosition = position
+		}
+
+		// Calculate position based on determined placement
+		switch (newPosition) {
+			// Top positions
+			case 'top':
+				newX = centerHorizontally(triggerRect, popoverRect)
+				newY = triggerRect.top - offset - popoverRect.height
+				break
+			case 'top-start':
+				newX = triggerRect.left
+				newY = triggerRect.top - offset - popoverRect.height
+				break
+			case 'top-end':
+				newX = triggerRect.right - popoverRect.width
+				newY = triggerRect.top - offset - popoverRect.height
+				break
+
+			// Bottom positions
+			case 'bottom':
+				newX = centerHorizontally(triggerRect, popoverRect)
+				newY = triggerRect.bottom + offset
+				break
+			case 'bottom-start':
+				newX = triggerRect.left
+				newY = triggerRect.bottom + offset
+				break
+			case 'bottom-end':
+				newX = triggerRect.right - popoverRect.width
+				newY = triggerRect.bottom + offset
+				break
+
+			// Left positions
+			case 'left':
+				newX = triggerRect.left - offset - popoverRect.width
+				newY = centerVertically(triggerRect, popoverRect)
+				break
+			case 'left-start':
+				newX = triggerRect.left - offset - popoverRect.width
+				newY = triggerRect.top
+				break
+			case 'left-end':
+				newX = triggerRect.left - offset - popoverRect.width
+				newY = triggerRect.bottom - popoverRect.height
+				break
+
+			// Right positions
+			case 'right':
+				newX = triggerRect.right + offset
+				newY = centerVertically(triggerRect, popoverRect)
+				break
+			case 'right-start':
+				newX = triggerRect.right + offset
+				newY = triggerRect.top
+				break
+			case 'right-end':
+				newX = triggerRect.right + offset
+				newY = triggerRect.bottom - popoverRect.height
+				break
+		}
+
+		// Ensure popover stays within viewport
+		newX = Math.max(
+			viewportMargin,
+			Math.min(newX, viewport.width - popoverRect.width - viewportMargin),
+		)
+		newY = Math.max(
+			viewportMargin,
+			Math.min(newY, viewport.height - popoverRect.height - viewportMargin),
+		)
+
+		positionX = newX
+		positionY = newY
+		actualPosition = newPosition
+	}
+
+	const handleClickOutside = (event: MouseEvent) => {
+		if (!open || !closeOnClickOutside) return
+
+		const target = event.target as Node
+		if (
+			popoverElement &&
+			!popoverElement.contains(target) &&
+			triggerElement &&
+			!triggerElement.contains(target)
+		) {
+			close()
+		}
+	}
+
+	const handleKeydown = (event: KeyboardEvent) => {
+		if (!open || !closeOnEscape) return
+
+		if (event.key === 'Escape') {
+			event.preventDefault()
+			close()
+		}
+	}
+
+	// Position popover when it opens
+	$effect(() => {
+		if (open && triggerElement && popoverElement) {
+			tick().then(() => {
+				calculatePosition()
+			})
+		}
+	})
+
+	onMount(() => {
+		const cleanup: (() => void)[] = []
+
+		if (closeOnClickOutside) {
+			document.addEventListener('click', handleClickOutside)
+			cleanup.push(() => document.removeEventListener('click', handleClickOutside))
+		}
+
+		if (closeOnEscape) {
+			document.addEventListener('keydown', handleKeydown)
+			cleanup.push(() => document.removeEventListener('keydown', handleKeydown))
+		}
+
+		return () => {
+			cleanup.forEach((fn) => fn())
+		}
+	})
+</script>
+
+<svelte:window onresize={calculatePosition} onscroll={calculatePosition} />
+
+<div
+	bind:this={triggerElement}
+	class="popover-trigger"
+	style:--trigger-display={triggerDisplay}
+	style:--trigger-flex={triggerFlex}
+>
+	{@render trigger()}
+</div>
+
+{#if open}
+	<div
+		bind:this={popoverElement}
+		class="popover-content {className}"
+		{role}
+		aria-label={ariaLabel}
+		data-position={actualPosition}
+		style:--popover-x="{positionX}px"
+		style:--popover-y="{positionY}px"
+	>
+		{@render content({ close })}
+	</div>
+{/if}
+
+<style>
+	.popover-trigger {
+		display: var(--trigger-display, inline-block);
+		flex: var(--trigger-flex);
+	}
+
+	.popover-content {
+		/* Positioning only - no visual styling */
+		position: fixed;
+		top: var(--popover-y);
+		left: var(--popover-x);
+		z-index: var(--popover-z-index, var(--layer-tooltip, 1000));
+	}
+</style>

package/src/types.ts

@@ -0,0 +1,14 @@
+export type Position =
+	| 'top'
+	| 'top-start'
+	| 'top-end'
+	| 'bottom'
+	| 'bottom-start'
+	| 'bottom-end'
+	| 'left'
+	| 'left-start'
+	| 'left-end'
+	| 'right'
+	| 'right-start'
+	| 'right-end'
+	| 'auto'