@hanzo/ui 8.0.6 → 8.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzo/ui",
-  "version": "8.0.6",
+  "version": "8.0.7",
   "type": "module",
   "description": "Hanzo UI \u2014 the one cross-platform component library on @hanzo/gui. The product/app layer (charts, metrics, page headers, status tags, rich empty states, combobox, slide-over, toasts, drag-reorder, labeled field rows, provider/product marks) + the metadata-driven record layer (@hanzo/data: RecordsView, DataTable, board, typed field editors) + the calm dark-first tokens and motion. Presentational, host-agnostic (data/effects injected), clean-room. Web + native (iOS) + desktop.",
   "exports": {
@@ -78,6 +78,7 @@
     "@hanzo/gui": ">=7.2.2",
     "@hanzo/ui-shadcn": ">=5.7.0",
     "@hanzo/usage": ">=0.1.0",
+    "@hanzogui/next-theme": ">=7.3.0",
     "react": ">=19"
   },
   "peerDependenciesMeta": {
@@ -95,6 +96,9 @@
     },
     "@hanzo/usage": {
       "optional": true
+    },
+    "@hanzogui/next-theme": {
+      "optional": true
     }
   },
   "devDependencies": {

package/src/product/ComboBox.tsx

@@ -1,22 +1,23 @@
 'use client'
 
 /**
- * ComboBox — a typeable select: a text input the user can type any value into,
- * PLUS a popover of LIVE options (filtered by what's typed) they can pick from.
- * The value is always exactly the input text, so a custom id is inherently
- * supported — selecting an option just fills the input. This is the ONE way the
- * console offers "pick from a live list OR type your own" (the model field, the
- * tool field). Prop-driven + self-contained (options/loading/error injected by the
- * caller), so it is orthogonal to the data source and lifts into `@hanzo/ui`.
+ * ComboBox — a typeable select: a text input the user can type any value into, PLUS a
+ * menu of LIVE options (filtered by what's typed) they can pick from. The value is
+ * always exactly the input text, so a custom id is inherently supported. Prop-driven +
+ * self-contained (options/loading/error injected by the caller).
  *
- * Idiom: the same @hanzo/gui Popover shell as OrgSwitcher/SelectMenu (bordered,
- * elevate, `$color2`). Options render in a portal above the DetailPane SlideOver.
+ * Uses the ONE shared menu spec (MenuPanel + MenuItemView) so options look identical to
+ * every other menu, and the SAME portal-theme fix (PortalTheme) so the list renders
+ * correctly through the portal above a SlideOver and under a nested `<Theme>`.
  */
 import { useMemo, useState } from 'react'
-import { Button, Input, Popover, Spinner, Text, XStack, YStack } from '@hanzo/gui'
-import { Check, ChevronDown, RefreshCw } from '@hanzogui/lucide-icons-2'
+import { Button, Input, Popover, Spinner, Text, XStack } from '@hanzo/gui'
+import { ChevronDown, RefreshCw } from '@hanzogui/lucide-icons-2'
 
 import { filterOptions, type ComboOption } from './combobox/filter'
+import { MenuItemView, MenuPanel } from './menu/items'
+import { PortalTheme, useThemeName } from './menu/portal-theme'
+import { menuKeyDown } from './menu/roving'
 
 export type { ComboOption } from './combobox/filter'
 
@@ -49,6 +50,7 @@ export function ComboBox({
   minWidth?: number
 }) {
   const [open, setOpen] = useState(false)
+  const themeName = useThemeName()
   const filtered = useMemo(() => filterOptions(options, value), [options, value])
 
   const pick = (v: string) => {
@@ -62,7 +64,7 @@ export function ComboBox({
         <Input
           flex={1}
           value={value}
-          onChangeText={(v) => {
+          onChangeText={(v: string) => {
             onChange(v)
             if (!open) setOpen(true)
           }}
@@ -83,65 +85,43 @@ export function ComboBox({
         </Popover.Trigger>
       </XStack>
 
-      <Popover.Content bordered elevate p="$1.5" minW={minWidth} bg="$color2" borderColor="$borderColor">
-        <YStack gap="$0.5" minW={minWidth} maxH={300} overflow="scroll">
-          {loading ? (
-            <XStack items="center" gap="$2" px="$2.5" py="$2">
-              <Spinner size="small" color="$color11" />
-              <Text fontSize="$2" color="$color10">
-                Loading options…
+      <Popover.Content bg="transparent" borderWidth={0} p={0} elevation={0}>
+        <PortalTheme name={themeName}>
+          <MenuPanel minWidth={minWidth} maxHeight={300} onKeyDown={(e) => menuKeyDown(e, () => setOpen(false))}>
+            {loading ? (
+              <XStack items="center" gap="$2" px="$2" py="$2">
+                <Spinner size="small" color="$color11" />
+                <Text fontSize="$2" color="$color10">
+                  Loading options…
+                </Text>
+              </XStack>
+            ) : error ? (
+              <XStack items="center" gap="$2" px="$2" py="$2">
+                <Text fontSize="$2" color="$color10" flex={1} numberOfLines={2}>
+                  {error}
+                </Text>
+                {onRetry ? (
+                  <Button size="$1" chromeless icon={<RefreshCw size={12} />} onPress={onRetry} aria-label="Retry" />
+                ) : null}
+              </XStack>
+            ) : filtered.length === 0 ? (
+              <Text fontSize="$2" color="$color10" px="$2" py="$2">
+                {emptyText}
               </Text>
-            </XStack>
-          ) : error ? (
-            <XStack items="center" gap="$2" px="$2.5" py="$2">
-              <Text fontSize="$2" color="$color10" flex={1} numberOfLines={2}>
-                {error}
-              </Text>
-              {onRetry ? (
-                <Button size="$1" chromeless icon={<RefreshCw size={12} />} onPress={onRetry} aria-label="Retry" />
-              ) : null}
-            </XStack>
-          ) : filtered.length === 0 ? (
-            <Text fontSize="$2" color="$color10" px="$2.5" py="$2">
-              {emptyText}
-            </Text>
-          ) : (
-            filtered.map((o) => (
-              <Row key={o.value} option={o} active={o.value === value} onPress={() => pick(o.value)} />
-            ))
-          )}
-        </YStack>
+            ) : (
+              filtered.map((o) => (
+                <MenuItemView
+                  key={o.value}
+                  label={o.label ?? o.value}
+                  description={o.hint}
+                  selected={o.value === value}
+                  onSelect={() => pick(o.value)}
+                />
+              ))
+            )}
+          </MenuPanel>
+        </PortalTheme>
       </Popover.Content>
     </Popover>
   )
 }
-
-function Row({ option, active, onPress }: { option: ComboOption; active: boolean; onPress: () => void }) {
-  return (
-    <XStack
-      items="center"
-      gap="$2"
-      px="$2.5"
-      py="$1.5"
-      rounded="$3"
-      cursor="pointer"
-      hoverStyle={{ bg: '$color4' }}
-      bg={active ? '$color4' : 'transparent'}
-      onPress={onPress}
-    >
-      <XStack width={14} items="center" justify="center">
-        {active ? <Check size={13} /> : null}
-      </XStack>
-      <YStack flex={1} minW={0}>
-        <Text fontSize="$2" color="$color12" numberOfLines={1}>
-          {option.label ?? option.value}
-        </Text>
-        {option.hint ? (
-          <Text fontSize="$1" color="$color10" numberOfLines={1}>
-            {option.hint}
-          </Text>
-        ) : null}
-      </YStack>
-    </XStack>
-  )
-}

package/src/product/SelectMenu.tsx

@@ -1,16 +1,22 @@
 'use client'
 
 /**
- * SelectMenu — a compact, reusable dropdown select on @hanzo/gui Popover (the
- * console's proven dropdown idiom, same as OrgSwitcher/ScopeSwitcher). Renders a
- * labelled trigger ("All types", or the chosen option) and a popover list with a
- * check on the active option. Prop-driven + self-contained so it lifts into
- * `@hanzo/ui`. `value === null` is the "all"/unfiltered state.
+ * SelectMenu — a compact, reusable dropdown select on @hanzo/gui Popover. Renders a
+ * labelled trigger ("All types", or the chosen option) and a menu list with a check on
+ * the active option. Prop-driven + self-contained. `value === null` is the
+ * "all"/unfiltered state.
+ *
+ * Uses the ONE shared menu spec (MenuPanel + MenuItemView) so it is pixel-identical to
+ * DropdownMenu/ContextMenu, and the SAME portal-theme fix (PortalTheme) so it renders
+ * correctly through the portal under a nested `<Theme>`, light or dark.
  */
 import type { ReactElement } from 'react'
 import { useState } from 'react'
-import { Button, Popover, Text, XStack, YStack } from '@hanzo/gui'
-import { ChevronDown, Check } from '@hanzogui/lucide-icons-2'
+import { Button, Popover, Text } from '@hanzo/gui'
+import { ChevronDown } from '@hanzogui/lucide-icons-2'
+import { MenuItemView, MenuPanel } from './menu/items'
+import { PortalTheme, useThemeName } from './menu/portal-theme'
+import { menuKeyDown } from './menu/roving'
 
 export type SelectOption<T extends string> = { key: T; label: string }
 
@@ -32,6 +38,7 @@ export function SelectMenu<T extends string>({
   minWidth?: number
 }) {
   const [open, setOpen] = useState(false)
+  const themeName = useThemeName()
   const active = value === null ? null : options.find((o) => o.key === value) ?? null
   const triggerLabel = active ? active.label : allLabel
 
@@ -58,37 +65,16 @@ export function SelectMenu<T extends string>({
           </Text>
         </Button>
       </Popover.Trigger>
-      <Popover.Content bordered elevate p="$1.5" minW={minWidth} bg="$color2" borderColor="$borderColor">
-        <YStack gap="$0.5" minW={minWidth} maxH={320} overflow="scroll">
-          <Row label={allLabel} active={value === null} onPress={() => pick(null)} />
-          {options.map((o) => (
-            <Row key={o.key} label={o.label} active={value === o.key} onPress={() => pick(o.key)} />
-          ))}
-        </YStack>
+      <Popover.Content bg="transparent" borderWidth={0} p={0} elevation={0}>
+        <PortalTheme name={themeName}>
+          <MenuPanel minWidth={minWidth} maxHeight={320} onKeyDown={(e) => menuKeyDown(e, () => setOpen(false))}>
+            <MenuItemView label={allLabel} selected={value === null} onSelect={() => pick(null)} />
+            {options.map((o) => (
+              <MenuItemView key={o.key} label={o.label} selected={value === o.key} onSelect={() => pick(o.key)} />
+            ))}
+          </MenuPanel>
+        </PortalTheme>
       </Popover.Content>
     </Popover>
   )
 }
-
-function Row({ label, active, onPress }: { label: string; active: boolean; onPress: () => void }) {
-  return (
-    <XStack
-      items="center"
-      gap="$2"
-      px="$2.5"
-      py="$1.5"
-      rounded="$3"
-      cursor="pointer"
-      hoverStyle={{ bg: '$color4' }}
-      bg={active ? '$color4' : 'transparent'}
-      onPress={onPress}
-    >
-      <XStack width={14} items="center" justify="center">
-        {active ? <Check size={13} /> : null}
-      </XStack>
-      <Text fontSize="$2" color="$color12" flex={1} numberOfLines={1}>
-        {label}
-      </Text>
-    </XStack>
-  )
-}

package/src/product/ThemeToggle.tsx

@@ -1,25 +1,135 @@
 'use client'
 
 /**
- * Theme toggle — flips the console between dark and light via next-theme. The
- * provider already wires `NextThemeProvider` → `GuiProvider`, so setting the
- * theme here re-themes the whole tree. Shows the action's target icon (a sun in
- * dark mode, a moon in light mode).
+ * ThemeToggle — flips between dark and light. Framework-agnostic by default so
+ * Vite / Tauri / Express hosts can use it with NO Next dependency:
+ *
+ *   • Controlled:  <ThemeToggle theme={theme} onToggle={setTheme} />   (host owns theme)
+ *   • Uncontrolled (agnostic): <ThemeToggle onThemeChange={fn} />       (toggles the DOM
+ *                              `.dark` class + persists to localStorage)
+ *   • Uncontrolled (no props): <ThemeToggle />                          (console/Next —
+ *                              falls back to the OPTIONAL @hanzogui/next-theme path;
+ *                              if it cannot load, degrades to the agnostic DOM toggle)
+ *
+ * Shows the action's target icon (a sun in dark mode, a moon in light mode).
  */
+import type { ReactNode } from 'react'
+import { Component, Suspense, lazy, useState } from 'react'
 import { Button } from '@hanzo/gui'
-import { useThemeSetting } from '@hanzogui/next-theme'
 import { Moon, Sun } from '@hanzogui/lucide-icons-2'
 
-export function ThemeToggle() {
-  const { current, resolvedTheme, set } = useThemeSetting()
-  const isDark = (resolvedTheme ?? current ?? 'dark') !== 'light'
+export type ThemeMode = 'light' | 'dark'
+
+export type ThemeToggleProps = {
+  /** Controlled theme. Pair with `onToggle`/`onThemeChange` to fully control it. */
+  theme?: ThemeMode
+  /** Seed for uncontrolled mode (default: read from the DOM `.dark` class, else 'dark'). */
+  defaultTheme?: ThemeMode
+  /** Called with the next theme on toggle (alias of `onThemeChange`). */
+  onToggle?: (next: ThemeMode) => void
+  /** Called with the next theme on toggle. */
+  onThemeChange?: (next: ThemeMode) => void
+  /** @hanzo/gui Button size token (default "$2"). */
+  size?: string
+  /** aria-label override. */
+  label?: string
+}
+
+const STORAGE_KEY = 'theme'
+
+function readDomTheme(): ThemeMode | undefined {
+  if (typeof document === 'undefined') return undefined
+  const el = document.documentElement
+  if (el.classList.contains('dark')) return 'dark'
+  if (el.classList.contains('light')) return 'light'
+  try {
+    const ls = window.localStorage.getItem(STORAGE_KEY)
+    if (ls === 'light' || ls === 'dark') return ls
+  } catch {
+    /* localStorage may be unavailable */
+  }
+  return undefined
+}
+
+function applyDomTheme(next: ThemeMode): void {
+  if (typeof document === 'undefined') return
+  const el = document.documentElement
+  el.classList.toggle('dark', next === 'dark')
+  el.classList.toggle('light', next === 'light')
+  el.style.colorScheme = next
+  try {
+    window.localStorage.setItem(STORAGE_KEY, next)
+  } catch {
+    /* ignore */
+  }
+}
+
+/**
+ * The framework-agnostic toggle button. Controlled when `theme` is provided; otherwise
+ * self-managed via the DOM `.dark` class. No framework dependency — safe on any host.
+ */
+export function AgnosticThemeToggle({
+  theme,
+  defaultTheme,
+  onToggle,
+  onThemeChange,
+  size = '$2',
+  label,
+}: ThemeToggleProps) {
+  const controlled = theme !== undefined
+  const [internal, setInternal] = useState<ThemeMode>(() => theme ?? defaultTheme ?? readDomTheme() ?? 'dark')
+  const current: ThemeMode = controlled ? (theme as ThemeMode) : internal
+  const isDark = current === 'dark'
+
+  const toggle = () => {
+    const next: ThemeMode = isDark ? 'light' : 'dark'
+    if (!controlled) {
+      setInternal(next)
+      applyDomTheme(next)
+    }
+    onToggle?.(next)
+    onThemeChange?.(next)
+  }
+
   return (
     <Button
-      size="$2"
+      size={size as never}
       chromeless
       icon={isDark ? <Sun size={16} /> : <Moon size={16} />}
-      onPress={() => set(isDark ? 'light' : 'dark')}
-      aria-label={isDark ? 'Switch to light theme' : 'Switch to dark theme'}
+      onPress={toggle}
+      aria-label={label ?? (isDark ? 'Switch to light theme' : 'Switch to dark theme')}
     />
   )
 }
+
+// @hanzogui/next-theme is an OPTIONAL dependency — loaded only on the uncontrolled,
+// no-props path (console/Next). Lazily code-split so non-Next hosts never need it at
+// runtime; if it fails to load, the boundary below degrades to the agnostic toggle.
+const NextThemeToggle = lazy(() => import('./ThemeToggleNext'))
+
+class NextThemeBoundary extends Component<{ fallback: ReactNode; children: ReactNode }, { failed: boolean }> {
+  state = { failed: false }
+  static getDerivedStateFromError() {
+    return { failed: true }
+  }
+  render() {
+    return this.state.failed ? this.props.fallback : this.props.children
+  }
+}
+
+export function ThemeToggle(props: ThemeToggleProps) {
+  const injected =
+    props.theme !== undefined || props.onToggle !== undefined || props.onThemeChange !== undefined
+  if (injected) return <AgnosticThemeToggle {...props} />
+
+  // No props → keep the existing console/Next behaviour via the optional next-theme
+  // path, degrading to the agnostic DOM toggle if it is not installed.
+  const fallback = <AgnosticThemeToggle {...props} />
+  return (
+    <NextThemeBoundary fallback={fallback}>
+      <Suspense fallback={fallback}>
+        <NextThemeToggle size={props.size} label={props.label} />
+      </Suspense>
+    </NextThemeBoundary>
+  )
+}

package/src/product/ThemeToggleNext.tsx

@@ -0,0 +1,27 @@
+'use client'
+
+/**
+ * ThemeToggleNext — the @hanzogui/next-theme binding (console / Next). This is the ONLY
+ * module that imports @hanzogui/next-theme, so it stays an OPTIONAL dependency: the base
+ * ThemeToggle lazy-loads it (default export) and non-Next hosts never pull it in unless
+ * they import this component directly. UI is delegated to the framework-agnostic button
+ * in controlled mode, so every toggle looks identical.
+ */
+import { useThemeSetting } from '@hanzogui/next-theme'
+import { AgnosticThemeToggle, type ThemeToggleProps } from './ThemeToggle'
+
+function ThemeToggleNext({ size, label }: Pick<ThemeToggleProps, 'size' | 'label'>) {
+  const { current, resolvedTheme, set } = useThemeSetting()
+  const isDark = (resolvedTheme ?? current ?? 'dark') !== 'light'
+  return (
+    <AgnosticThemeToggle
+      theme={isDark ? 'dark' : 'light'}
+      onToggle={(next) => set(next)}
+      size={size}
+      label={label}
+    />
+  )
+}
+
+export default ThemeToggleNext
+export { ThemeToggleNext }

package/src/product/index.ts

@@ -47,6 +47,11 @@ export * from './BrandMark'
 export * from './OrgSwitcher'
 export * from './scope'
 
+// Menu — the ONE menu system: portal-theme-safe DropdownMenu (click) + ContextMenu
+// (right-click), both rendering the SAME item spec (MenuPanel/MenuItemView) so every
+// menu across the fleet is pixel-identical. SelectMenu/ComboBox share the same spec.
+export * from './menu'
+
 // The rest — every exported name below is unique across the layer.
 export * from './DataTable'
 export * from './EmptyState'
@@ -62,6 +67,7 @@ export * from './SelectMenu'
 export * from './SlideOver'
 export * from './StatusTag'
 export * from './ThemeToggle'
+export { ThemeToggleNext } from './ThemeToggleNext'
 export * from './Toast'
 export * from './color'
 

package/src/product/menu/ContextMenu.tsx

@@ -0,0 +1,114 @@
+'use client'
+
+/**
+ * ContextMenu — a right-click menu that renders the SAME shared item spec as
+ * DropdownMenu, so every menu in the fleet is identical. Built on the @hanzo/gui
+ * Portal with the SAME portal-theme fix as the dropdown: the menu is portaled to the
+ * root, escaping any nested `<Theme>`, so it re-applies the captured theme via
+ * <PortalTheme>. Web/desktop right-click (`onContextMenu`); on native — which has no
+ * right-click — the wrapped child renders untouched.
+ *
+ *   <ContextMenu items={[{ key:'copy', label:'Copy', icon:<Copy size={16}/>, onSelect:copy }]}>
+ *     <YStack>right-click me</YStack>
+ *   </ContextMenu>
+ */
+import type { ReactElement, MouseEvent } from 'react'
+import { cloneElement, useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react'
+import { Portal } from '@hanzo/gui'
+import { MenuPanel, renderMenuItems, type MenuItemSpec } from './items'
+import { PortalTheme, useThemeName } from './portal-theme'
+import { menuKeyDown } from './roving'
+
+const EDGE = 8 // keep this far from the viewport edge
+
+export type ContextMenuProps = {
+  /** The right-clickable target. Its `onContextMenu` is composed, not replaced. */
+  children: ReactElement
+  items: MenuItemSpec[]
+  disabled?: boolean
+  minWidth?: number
+  maxHeight?: number
+}
+
+export function ContextMenu({ children, items, disabled, minWidth = 200, maxHeight }: ContextMenuProps) {
+  const themeName = useThemeName()
+  const [state, setState] = useState<{ open: boolean; x: number; y: number }>({ open: false, x: 0, y: 0 })
+  const panelRef = useRef<HTMLElement | null>(null)
+
+  const close = useCallback(() => setState((s) => (s.open ? { ...s, open: false } : s)), [])
+
+  const openAt = (e: MouseEvent) => {
+    if (disabled) return
+    e.preventDefault()
+    e.stopPropagation()
+    setState({ open: true, x: e.clientX, y: e.clientY })
+  }
+
+  // Edge-flip before paint: clamp so the panel stays fully in the viewport.
+  useLayoutEffect(() => {
+    if (!state.open || typeof window === 'undefined') return
+    const node = panelRef.current
+    if (!node) return
+    const r = node.getBoundingClientRect()
+    let x = state.x
+    let y = state.y
+    if (x + r.width > window.innerWidth - EDGE) x = Math.max(EDGE, window.innerWidth - r.width - EDGE)
+    if (y + r.height > window.innerHeight - EDGE) y = Math.max(EDGE, window.innerHeight - r.height - EDGE)
+    if (x !== state.x || y !== state.y) setState((s) => ({ ...s, x, y }))
+    // Focus the panel so keyboard nav works immediately.
+    node.focus?.()
+  }, [state.open, state.x, state.y])
+
+  // Dismiss on outside pointer, Escape, scroll, resize, blur.
+  useEffect(() => {
+    if (!state.open || typeof document === 'undefined') return
+    const onPointerDown = (e: PointerEvent) => {
+      if (panelRef.current && !panelRef.current.contains(e.target as Node)) close()
+    }
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') close()
+    }
+    document.addEventListener('pointerdown', onPointerDown, true)
+    document.addEventListener('keydown', onKey, true)
+    window.addEventListener('scroll', close, true)
+    window.addEventListener('resize', close)
+    window.addEventListener('blur', close)
+    return () => {
+      document.removeEventListener('pointerdown', onPointerDown, true)
+      document.removeEventListener('keydown', onKey, true)
+      window.removeEventListener('scroll', close, true)
+      window.removeEventListener('resize', close)
+      window.removeEventListener('blur', close)
+    }
+  }, [state.open, close])
+
+  const childOnContextMenu = (children.props as { onContextMenu?: (e: MouseEvent) => void }).onContextMenu
+  const target = cloneElement(children, {
+    onContextMenu: (e: MouseEvent) => {
+      childOnContextMenu?.(e)
+      openAt(e)
+    },
+  } as Partial<typeof children.props>)
+
+  return (
+    <>
+      {target}
+      {state.open ? (
+        <Portal>
+          <PortalTheme name={themeName}>
+            <MenuPanel
+              panelRef={(n) => (panelRef.current = n)}
+              minWidth={minWidth}
+              maxHeight={maxHeight}
+              tabIndex={-1}
+              onKeyDown={(e) => menuKeyDown(e, close)}
+              style={{ position: 'fixed', left: state.x, top: state.y, zIndex: 100000 }}
+            >
+              {renderMenuItems(items, close)}
+            </MenuPanel>
+          </PortalTheme>
+        </Portal>
+      ) : null}
+    </>
+  )
+}

package/src/product/menu/DropdownMenu.tsx

@@ -0,0 +1,76 @@
+'use client'
+
+/**
+ * DropdownMenu — a portal-theme-safe dropdown on the @hanzo/gui Popover (the proven
+ * console idiom, same shell as SelectMenu/ComboBox). Declarative `items`; renders the
+ * ONE shared menu-item spec so it is pixel-identical to every other menu. Opens under
+ * a nested `<Theme>` correctly because the portaled content re-applies the captured
+ * theme (see PortalTheme).
+ *
+ *   <DropdownMenu
+ *     trigger={<Button>Actions</Button>}
+ *     items={[
+ *       { key: 'rename', label: 'Rename', icon: <Pencil size={16} />, onSelect: rename },
+ *       { type: 'separator' },
+ *       { key: 'del', label: 'Delete', destructive: true, onSelect: del },
+ *     ]}
+ *   />
+ */
+import type { ReactElement } from 'react'
+import { Popover, useControllableState } from '@hanzo/gui'
+import { MenuPanel, renderMenuItems, type MenuItemSpec } from './items'
+import { PortalTheme, useThemeName } from './portal-theme'
+import { menuKeyDown } from './roving'
+
+export type DropdownMenuProps = {
+  /** The clickable element. Cloned as the Popover trigger (`asChild`). */
+  trigger: ReactElement
+  items: MenuItemSpec[]
+  /** Controlled open state. Omit for uncontrolled. */
+  open?: boolean
+  defaultOpen?: boolean
+  onOpenChange?: (open: boolean) => void
+  /** Popover placement (default `bottom-start`). */
+  placement?: React.ComponentProps<typeof Popover>['placement']
+  minWidth?: number
+  maxHeight?: number
+}
+
+export function DropdownMenu({
+  trigger,
+  items,
+  open,
+  defaultOpen = false,
+  onOpenChange,
+  placement = 'bottom-start',
+  minWidth = 200,
+  maxHeight,
+}: DropdownMenuProps) {
+  const [isOpen, setOpen] = useControllableState({
+    prop: open,
+    defaultProp: defaultOpen,
+    onChange: onOpenChange,
+  })
+  // Capture the resolved theme HERE, where theme context is still available; the
+  // Popover.Content portals out of it and re-applies it via <PortalTheme>.
+  const themeName = useThemeName()
+
+  return (
+    <Popover open={isOpen} onOpenChange={setOpen} placement={placement} allowFlip>
+      <Popover.Trigger asChild>{trigger}</Popover.Trigger>
+      <Popover.Content
+        // The visible surface is our MenuPanel — keep Content a transparent shell.
+        bg="transparent"
+        borderWidth={0}
+        p={0}
+        elevation={0}
+      >
+        <PortalTheme name={themeName}>
+          <MenuPanel minWidth={minWidth} maxHeight={maxHeight} onKeyDown={(e) => menuKeyDown(e, () => setOpen(false))}>
+            {renderMenuItems(items, () => setOpen(false))}
+          </MenuPanel>
+        </PortalTheme>
+      </Popover.Content>
+    </Popover>
+  )
+}

package/src/product/menu/index.ts

@@ -0,0 +1,15 @@
+// @hanzo/ui/product menu — ONE menu system. Portal-theme-safe DropdownMenu (click)
+// and ContextMenu (right-click) both render the SAME item spec, so every menu across
+// the fleet is pixel-identical. See items.tsx for the shared spec.
+
+export { DropdownMenu, type DropdownMenuProps } from './DropdownMenu'
+export { ContextMenu, type ContextMenuProps } from './ContextMenu'
+export {
+  MenuPanel,
+  MenuItemView,
+  MenuSeparatorView,
+  MenuLabelView,
+  renderMenuItems,
+  type MenuItemSpec,
+} from './items'
+export { PortalTheme } from './portal-theme'