@puredesktop/puredesktop-ui-bridge 1.0.0-beta.1

package/src/components/common/dropdown/MenuDropdownSubmenu.tsx

@@ -0,0 +1,145 @@
+import { useRef, useState } from 'react'
+import { ChevronRight } from 'lucide-react'
+import { styled } from 'styled-components'
+import { CollapsibleGrid } from '../containers/CollapsibleGrid.js'
+import { FlexCol } from '../containers/flex.js'
+import { MenuDropdownEntry } from './MenuDropdownEntry.js'
+import { MenuPortal } from './MenuPortal.js'
+import type { MenuActionItem, MenuSubmenuItem } from './menuTypes.js'
+
+const SUBMENU_HOVER_CLOSE_MS = 120
+
+//#region styled-components
+
+const StyledRow = styled.div<{ $disabled?: boolean; $open: boolean }>`
+  position: relative;
+  opacity: ${p => (p.$disabled ? 0.45 : 1)};
+  pointer-events: ${p => (p.$disabled ? 'none' : 'auto')};
+`
+
+const StyledTrigger = styled.button<{ $open: boolean }>`
+  display: grid;
+  grid-template-columns: 1fr auto;
+  align-items: center;
+  gap: var(--platform-spacing-sm);
+  width: 100%;
+  padding: var(--platform-spacing-xs) var(--platform-spacing-sm);
+  border: none;
+  border-radius: 0;
+  background: ${p =>
+    p.$open ? 'var(--platform-colors-surface-hover)' : 'transparent'};
+  color: var(--platform-colors-text);
+  font-size: var(--platform-typography-font-size-base);
+  text-align: left;
+  cursor: pointer;
+
+  &:hover {
+    background: var(--platform-colors-surface-hover);
+  }
+`
+
+const StyledFlyoutPanel = styled(CollapsibleGrid)`
+  padding: var(--platform-spacing-xs);
+  border: 1px solid var(--platform-colors-border);
+  border-radius: 0;
+  background: var(--platform-colors-elevated);
+  box-shadow: var(--platform-shadow-md);
+
+  &[data-open='true'] {
+    min-width: 180px;
+  }
+
+  &[data-open='false'] {
+    box-shadow: none;
+  }
+`
+
+//#endregion
+
+export interface MenuDropdownSubmenuProps {
+  item: MenuSubmenuItem
+  depth: number
+  onSelect: (item: MenuActionItem) => void
+}
+
+export function MenuDropdownSubmenu({
+  item,
+  depth,
+  onSelect,
+}: MenuDropdownSubmenuProps): React.ReactElement {
+  const [open, setOpen] = useState(false)
+  const rowRef = useRef<HTMLDivElement>(null)
+  const closeTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  const clearCloseTimer = (): void => {
+    if (closeTimerRef.current !== null) {
+      clearTimeout(closeTimerRef.current)
+      closeTimerRef.current = null
+    }
+  }
+
+  const scheduleClose = (): void => {
+    clearCloseTimer()
+    closeTimerRef.current = setTimeout(() => {
+      setOpen(false)
+      closeTimerRef.current = null
+    }, SUBMENU_HOVER_CLOSE_MS)
+  }
+
+  const handleOpen = (): void => {
+    if (item.disabled) return
+    clearCloseTimer()
+    setOpen(true)
+  }
+
+  return (
+    <StyledRow
+      ref={rowRef}
+      $disabled={item.disabled}
+      $open={open}
+      onMouseEnter={handleOpen}
+      onMouseLeave={scheduleClose}
+    >
+      <StyledTrigger
+        type="button"
+        role="menuitem"
+        aria-expanded={open}
+        aria-haspopup="menu"
+        disabled={item.disabled}
+        $open={open}
+        onClick={event => event.stopPropagation()}
+      >
+        <span>{item.label}</span>
+        <ChevronRight size={14} strokeWidth={2} />
+      </StyledTrigger>
+      <MenuPortal
+        anchorRef={rowRef}
+        open={open}
+        placement="after-start"
+        depth={depth}
+        onMouseEnter={handleOpen}
+        onMouseLeave={scheduleClose}
+      >
+        <StyledFlyoutPanel
+          open={open}
+          animationDirection="x"
+          indent={false}
+          role="menu"
+          aria-label={item.label}
+        >
+          <FlexCol $gap="xs" $width="100%">
+            {item.items.map((entry, index) => (
+              <MenuDropdownEntry
+                key={entry.type === 'divider' ? `divider-${index}` : entry.id}
+                entry={entry}
+                index={index}
+                depth={depth}
+                onSelect={onSelect}
+              />
+            ))}
+          </FlexCol>
+        </StyledFlyoutPanel>
+      </MenuPortal>
+    </StyledRow>
+  )
+}

package/src/components/common/dropdown/MenuPanel.tsx

@@ -0,0 +1,69 @@
+import { styled } from 'styled-components'
+import { CollapsibleGrid } from '../containers/CollapsibleGrid.js'
+
+export const StyledMenuPanel = styled(CollapsibleGrid)<{
+  $fillWidth?: boolean
+}>`
+  box-sizing: border-box;
+  width: ${p => (p.$fillWidth ? '100%' : 'max-content')};
+  min-width: ${p => (p.$fillWidth ? '0' : '220px')};
+  max-height: inherit;
+  overflow: hidden;
+  padding: var(--platform-spacing-xs);
+  border: 1px solid var(--platform-colors-border);
+  border-radius: var(--platform-radius-md);
+  background: var(--platform-colors-elevated);
+  box-shadow: var(--platform-shadow-md);
+
+  &[data-animation-direction='y'] {
+    width: ${p => (p.$fillWidth ? '100%' : 'max-content')};
+  }
+
+  &[data-open='false'] {
+    box-shadow: none;
+  }
+
+  & > .content {
+    max-height: inherit;
+    overflow-x: hidden;
+    overflow-y: auto;
+  }
+`
+
+/** Chat composer menus — matches ChatBox surface (bg, 8px radius, 13px items). */
+export const StyledChatMenuPanel = styled(StyledMenuPanel)`
+  min-width: 160px;
+  padding: 4px;
+  border-radius: 8px;
+  background: var(--platform-colors-bg);
+  box-shadow: 0 4px 16px rgb(from var(--platform-colors-text) r g b / 0.08);
+
+  &[data-open='false'] {
+    box-shadow: none;
+  }
+
+  button[role='menuitem'] {
+    min-height: 28px;
+    padding: 4px 8px;
+    border-radius: 6px;
+    font-size: 13px;
+    line-height: 1.4;
+  }
+
+  button[role='menuitem']:hover:not(:disabled) {
+    background: rgb(from var(--platform-colors-text) r g b / 0.05);
+  }
+`
+
+/** Wide picker panels — still CollapsibleGrid / StyledMenuPanel underneath. */
+export const StyledPaletteMenuPanel = styled(StyledMenuPanel)`
+  min-width: min(310px, calc(100vw - 24px));
+  padding: 6px;
+  border-radius: 12px;
+`
+
+export const StyledWorkspaceMenuPanel = styled(StyledMenuPanel)`
+  min-width: min(320px, calc(100vw - 24px));
+  padding: 6px;
+  border-radius: 10px;
+`

package/src/components/common/dropdown/MenuPortal.tsx

@@ -0,0 +1,162 @@
+import {
+  useLayoutEffect,
+  useRef,
+  useState,
+  type ComponentPropsWithoutRef,
+  type CSSProperties,
+  type ReactNode,
+  type RefObject,
+} from 'react'
+import { createPortal } from 'react-dom'
+import { styled } from 'styled-components'
+import {
+  COLLAPSIBLE_GRID_DURATION_MS,
+  useOpenTransition,
+} from '../containers/useOpenTransition.js'
+import { MENU_PORTAL_ID } from './menuPortalConstants.js'
+import {
+  resolveMenuViewportLayout,
+  type MenuWidthMode,
+  type ResolvedMenuLayout,
+} from './menuViewportPosition.js'
+import {
+  useMenuAnchorPosition,
+  type MenuPlacement,
+} from './useMenuAnchorPosition.js'
+
+//#region styled-components
+
+const StyledSurface = styled.div<{ $depth: number }>`
+  position: fixed;
+  z-index: calc(var(--platform-z-index-zi-app-modal) + 20 + ${p => p.$depth});
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+`
+
+//#endregion
+
+export interface MenuPortalProps
+  extends Omit<ComponentPropsWithoutRef<'div'>, 'children'> {
+  anchorRef: RefObject<HTMLElement | null>
+  /** Section trigger; used with `below-menubar-start` for horizontal alignment. */
+  alignRef?: RefObject<HTMLElement | null>
+  open: boolean
+  placement: MenuPlacement
+  point?: { x: number; y: number } | null
+  depth?: number
+  durationMs?: number
+  widthMode?: MenuWidthMode
+  minWidth?: number
+  children: ReactNode
+}
+
+export function MenuPortal({
+  anchorRef,
+  alignRef,
+  open,
+  placement,
+  point,
+  depth = 0,
+  durationMs = COLLAPSIBLE_GRID_DURATION_MS,
+  widthMode = 'intrinsic',
+  minWidth,
+  children,
+  style,
+  ...rest
+}: MenuPortalProps): React.ReactElement | null {
+  const { mounted } = useOpenTransition(open, durationMs)
+  const draftPosition = useMenuAnchorPosition({
+    anchorRef,
+    alignRef,
+    active: mounted,
+    placement,
+    point,
+  })
+  const surfaceRef = useRef<HTMLDivElement>(null)
+  const [portalRoot, setPortalRoot] = useState<HTMLElement | null>(null)
+  const [layout, setLayout] = useState<ResolvedMenuLayout | null>(null)
+
+  useLayoutEffect(() => {
+    setPortalRoot(document.getElementById(MENU_PORTAL_ID))
+  }, [])
+
+  useLayoutEffect(() => {
+    if (!mounted || !draftPosition || !surfaceRef.current) {
+      setLayout(null)
+      return
+    }
+
+    const anchorElement = anchorRef.current
+    const anchorRect =
+      placement === 'at-point' && point
+        ? {
+            top: point.y,
+            bottom: point.y,
+            left: point.x,
+            right: point.x,
+            width: 0,
+            height: 0,
+          }
+        : anchorElement?.getBoundingClientRect()
+
+    if (!anchorRect) {
+      setLayout(null)
+      return
+    }
+
+    const menuRect = surfaceRef.current.getBoundingClientRect()
+
+    setLayout(
+      resolveMenuViewportLayout({
+        anchorRect,
+        preferredTop: draftPosition.top,
+        preferredLeft: draftPosition.left,
+        placement,
+        menuWidth: menuRect.width,
+        menuHeight: menuRect.height,
+        widthMode,
+        minWidth,
+      }),
+    )
+  }, [
+    alignRef,
+    anchorRef,
+    draftPosition,
+    minWidth,
+    mounted,
+    placement,
+    point,
+    widthMode,
+    children,
+  ])
+
+  if (!mounted || !draftPosition || !portalRoot) return null
+
+  const surfaceStyle: CSSProperties = layout
+    ? {
+        top: layout.top,
+        left: layout.left,
+        maxHeight: layout.maxHeight,
+        ...(layout.width !== undefined ? { width: layout.width } : {}),
+        ...style,
+      }
+    : {
+        top: draftPosition.top,
+        left: draftPosition.left,
+        ...style,
+      }
+
+  return createPortal(
+    <StyledSurface
+      ref={surfaceRef}
+      data-platform-menu-surface
+      $depth={depth}
+      style={surfaceStyle}
+      {...rest}
+    >
+      {children}
+    </StyledSurface>,
+    portalRoot,
+  )
+}

package/src/components/common/dropdown/MenuPortalLayer.tsx

@@ -0,0 +1,6 @@
+import { MENU_PORTAL_ID } from './menuPortalConstants.js'
+
+/** Mount once under `ThemeProvider`; all menu surfaces portal here. */
+export function MenuPortalLayer(): React.ReactElement {
+  return <div id={MENU_PORTAL_ID} />
+}

package/src/components/common/dropdown/SelectMenu.tsx

@@ -0,0 +1,243 @@
+import type { CSSProperties, ReactNode, RefObject } from 'react'
+import { useCallback, useEffect, useLayoutEffect, useState } from 'react'
+import { createPortal } from 'react-dom'
+import { styled } from 'styled-components'
+import {
+  COLLAPSIBLE_GRID_DURATION_MS,
+  useOpenTransition,
+} from '../containers/useOpenTransition.js'
+import { FlexCol } from '../containers/flex.js'
+import {
+  StyledChatMenuPanel,
+  StyledMenuPanel,
+  StyledPaletteMenuPanel,
+  StyledWorkspaceMenuPanel,
+} from './MenuPanel.js'
+import {
+  resolveSelectMenuLayout,
+  type SelectMenuLayout,
+  type SelectMenuPanelVariant,
+  type SelectMenuPlacement,
+  type SelectMenuWidthMode,
+} from './selectMenuLayout.js'
+
+export type {
+  SelectMenuPanelVariant,
+  SelectMenuPlacement,
+  SelectMenuWidthMode,
+} from './selectMenuLayout.js'
+
+export interface SelectMenuProps {
+  open: boolean
+  anchorRef: RefObject<HTMLElement | null>
+  onClose: () => void
+  placement?: SelectMenuPlacement
+  widthMode?: SelectMenuWidthMode
+  minWidth?: number
+  panelVariant?: SelectMenuPanelVariant
+  attachToAnchor?: boolean
+  wrapChildren?: boolean
+  role?: 'menu' | 'listbox' | 'dialog'
+  children: ReactNode
+  'aria-label'?: string
+}
+
+function resolvePanelComponent(variant: SelectMenuPanelVariant) {
+  switch (variant) {
+    case 'quiet':
+      return StyledChatMenuPanel
+    case 'palette':
+      return StyledPaletteMenuPanel
+    case 'workspace':
+      return StyledWorkspaceMenuPanel
+    default:
+      return StyledMenuPanel
+  }
+}
+
+export function SelectMenu({
+  open,
+  anchorRef,
+  onClose,
+  placement = 'below',
+  widthMode = 'intrinsic',
+  minWidth,
+  panelVariant = 'default',
+  attachToAnchor = true,
+  wrapChildren = true,
+  role = 'menu',
+  children,
+  'aria-label': ariaLabel = 'Menu',
+}: SelectMenuProps): React.ReactElement | null {
+  const { mounted } = useOpenTransition(open, COLLAPSIBLE_GRID_DURATION_MS)
+  const [layout, setLayout] = useState<SelectMenuLayout | null>(null)
+  const Panel = resolvePanelComponent(panelVariant)
+
+  const updateLayout = useCallback(() => {
+    const anchor = anchorRef.current
+    if (!anchor) {
+      setLayout(null)
+      return
+    }
+
+    setLayout(
+      resolveSelectMenuLayout({
+        anchorRect: anchor.getBoundingClientRect(),
+        placement,
+        widthMode,
+        minWidth,
+        attachToAnchor,
+      }),
+    )
+  }, [anchorRef, attachToAnchor, minWidth, placement, widthMode])
+
+  useLayoutEffect(() => {
+    if (!mounted) {
+      setLayout(null)
+      return
+    }
+    updateLayout()
+  }, [mounted, updateLayout])
+
+  useEffect(() => {
+    if (!mounted) return
+
+    const onResize = () => updateLayout()
+    window.addEventListener('resize', onResize)
+    window.addEventListener('scroll', onResize, true)
+    return () => {
+      window.removeEventListener('resize', onResize)
+      window.removeEventListener('scroll', onResize, true)
+    }
+  }, [mounted, updateLayout])
+
+  useEffect(() => {
+    if (!open) return
+
+    const onPointerDown = (event: MouseEvent): void => {
+      const target = event.target
+      if (!(target instanceof Node)) return
+      const el = target instanceof Element ? target : target.parentElement
+      if (!el) return
+      if (el.closest('[data-platform-select-menu]') !== null) return
+      if (anchorRef.current?.contains(el)) return
+      onClose()
+    }
+
+    const onKeyDown = (event: KeyboardEvent): void => {
+      if (event.key === 'Escape') onClose()
+    }
+
+    document.addEventListener('mousedown', onPointerDown)
+    document.addEventListener('keydown', onKeyDown)
+    return () => {
+      document.removeEventListener('mousedown', onPointerDown)
+      document.removeEventListener('keydown', onKeyDown)
+    }
+  }, [anchorRef, onClose, open])
+
+  if (!mounted || !layout) return null
+
+  const shellStyle: CSSProperties = {
+    left: layout.left,
+    maxHeight: layout.maxHeight,
+    minWidth: layout.minWidth,
+    ...(layout.width !== undefined ? { width: layout.width } : {}),
+    ...(layout.top !== undefined ? { top: layout.top } : {}),
+    ...(layout.bottom !== undefined ? { bottom: layout.bottom } : {}),
+  }
+
+  const body = wrapChildren ? (
+    <FlexCol $gap="xs" $width="100%">
+      {children}
+    </FlexCol>
+  ) : (
+    children
+  )
+
+  return createPortal(
+    <StyledPortalShell style={shellStyle}>
+      <Panel
+        data-platform-select-menu
+        open={open}
+        indent={false}
+        $fillWidth={widthMode === 'anchor'}
+        role={role}
+        aria-label={ariaLabel}
+      >
+        {body}
+      </Panel>
+    </StyledPortalShell>,
+    document.body,
+  )
+}
+
+const StyledPortalShell = styled.div`
+  position: fixed;
+  z-index: calc(var(--platform-z-index-zi-app-modal) + 20);
+  display: flex;
+  flex-direction: column;
+  box-sizing: border-box;
+  width: max-content;
+  max-width: calc(100vw - 16px);
+  pointer-events: auto;
+`
+
+export interface SelectMenuItemProps {
+  label: string
+  selected?: boolean
+  disabled?: boolean
+  tone?: 'default' | 'danger'
+  onSelect: () => void
+}
+
+export function SelectMenuItem({
+  label,
+  selected = false,
+  disabled = false,
+  tone = 'default',
+  onSelect,
+}: SelectMenuItemProps): React.ReactElement {
+  return (
+    <StyledItem
+      type="button"
+      role="menuitem"
+      disabled={disabled}
+      $selected={selected}
+      $tone={tone}
+      onClick={() => {
+        if (!disabled) onSelect()
+      }}
+    >
+      {label}
+    </StyledItem>
+  )
+}
+
+const StyledItem = styled.button<{
+  $selected?: boolean
+  $tone: 'default' | 'danger'
+}>`
+  display: block;
+  width: 100%;
+  min-height: 30px;
+  padding: 5px 8px;
+  border: none;
+  border-radius: var(--platform-radius-sm);
+  background: ${({ $selected }) =>
+    $selected ? 'var(--platform-colors-surface-hover)' : 'transparent'};
+  color: ${({ $tone }) =>
+    $tone === 'danger'
+      ? 'var(--platform-colors-text-danger)'
+      : 'var(--platform-colors-text)'};
+  font: inherit;
+  font-size: var(--platform-typography-font-size-sm);
+  line-height: 1.3;
+  text-align: left;
+  cursor: ${({ disabled }) => (disabled ? 'not-allowed' : 'pointer')};
+  opacity: ${({ disabled }) => (disabled ? 0.45 : 1)};
+
+  &:hover:not(:disabled) {
+    background: var(--platform-colors-surface-hover);
+  }
+`

package/src/components/common/dropdown/SelectMenuControl.tsx

@@ -0,0 +1,23 @@
+import type { ReactNode, RefObject } from 'react'
+import { SelectMenu, type SelectMenuProps } from './SelectMenu.js'
+
+export interface SelectMenuControlProps
+  extends Omit<SelectMenuProps, 'children' | 'open' | 'onClose' | 'anchorRef'> {
+  anchorRef: RefObject<HTMLElement | null>
+  open: boolean
+  onClose: () => void
+  children: ReactNode | ((close: () => void) => ReactNode)
+}
+
+/** Portaled CollapsibleGrid menu — single entry point for all select-style dropdowns. */
+export function SelectMenuControl({
+  children,
+  onClose,
+  ...menuProps
+}: SelectMenuControlProps): React.ReactElement | null {
+  return (
+    <SelectMenu {...menuProps} onClose={onClose}>
+      {typeof children === 'function' ? children(onClose) : children}
+    </SelectMenu>
+  )
+}

package/src/components/common/dropdown/SelectMenuOptions.tsx

@@ -0,0 +1,38 @@
+import { SelectMenuItem } from './SelectMenu.js'
+
+export interface SelectMenuOption {
+  value: string
+  label: string
+  disabled?: boolean
+}
+
+export interface SelectMenuOptionsProps {
+  options: readonly SelectMenuOption[]
+  value: string
+  onValueChange: (value: string) => void
+  onClose: () => void
+}
+
+export function SelectMenuOptions({
+  options,
+  value,
+  onValueChange,
+  onClose,
+}: SelectMenuOptionsProps): React.ReactElement {
+  return (
+    <>
+      {options.map(option => (
+        <SelectMenuItem
+          key={option.value}
+          label={option.label}
+          selected={option.value === value}
+          disabled={option.disabled}
+          onSelect={() => {
+            onValueChange(option.value)
+            onClose()
+          }}
+        />
+      ))}
+    </>
+  )
+}

package/src/components/common/dropdown/menuPortalConstants.ts

@@ -0,0 +1,11 @@
+export const MENU_PORTAL_ID = 'platform-menu-portal'
+
+export function isMenuInteractionTarget(target: EventTarget | null): boolean {
+  if (!(target instanceof Node)) return false
+  const el = target instanceof Element ? target : target.parentElement
+  if (!el) return false
+  return (
+    el.closest('[data-platform-menu-surface]') !== null ||
+    el.closest('[data-platform-menu-trigger]') !== null
+  )
+}