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

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

@@ -0,0 +1,71 @@
+import type { RefObject } from 'react'
+import type { MenuWidthMode } from './menuViewportPosition.js'
+import type { MenuPlacement } from './useMenuAnchorPosition.js'
+
+export type MenuDivider = { type: 'divider' }
+
+export type MenuActionTone = 'default' | 'danger'
+
+export interface MenuActionItem {
+  type?: 'action'
+  id: string
+  label: string
+  disabled?: boolean
+  tone?: MenuActionTone
+  /** Display only until shell wires shortcuts */
+  shortcut?: string
+}
+
+export interface MenuSubmenuItem {
+  type: 'submenu'
+  id: string
+  label: string
+  items: MenuEntry[]
+  disabled?: boolean
+}
+
+export type MenuEntry = MenuActionItem | MenuDivider | MenuSubmenuItem
+
+export function isMenuDivider(entry: MenuEntry): entry is MenuDivider {
+  return entry.type === 'divider'
+}
+
+export function isMenuSubmenu(entry: MenuEntry): entry is MenuSubmenuItem {
+  return entry.type === 'submenu'
+}
+
+export interface MenuSection {
+  id: string
+  label: string
+  items: MenuEntry[]
+}
+
+export interface MenuBarProps {
+  sections: MenuSection[]
+  onSelectItem?: (sectionId: string, item: MenuActionItem) => void
+  'aria-label'?: string
+}
+
+export type MenuPanelVariant = 'default' | 'chat'
+
+export interface MenuDropdownProps {
+  sectionId: string
+  items: MenuEntry[]
+  open: boolean
+  /** Required when `placement` is `below-menubar-start`. */
+  menubarRef?: RefObject<HTMLElement | null>
+  triggerRef: RefObject<HTMLElement | null>
+  placement?: MenuPlacement
+  /** `anchor` sizes to the trigger; `intrinsic` sizes to menu content. */
+  widthMode?: MenuWidthMode
+  minWidth?: number
+  panelVariant?: MenuPanelVariant
+  onSelectItem?: (item: MenuActionItem) => void
+  onClose: () => void
+}
+
+export interface MenuBarTriggerProps {
+  section: MenuSection
+  open: boolean
+  onOpen: () => void
+}

package/src/components/common/dropdown/menuViewportPosition.test.ts

@@ -0,0 +1,139 @@
+import { describe, expect, it } from 'vitest'
+import {
+  MENU_ANCHOR_GAP_PX,
+  resolveMenuViewportLayout,
+} from './menuViewportPosition.js'
+
+describe('resolveMenuViewportLayout', () => {
+  it('clamps intrinsic menus that would overflow the right edge', () => {
+    const layout = resolveMenuViewportLayout({
+      anchorRect: {
+        top: 40,
+        bottom: 68,
+        left: 900,
+        right: 980,
+        width: 80,
+      },
+      preferredTop: 68 + MENU_ANCHOR_GAP_PX,
+      preferredLeft: 900,
+      placement: 'below-start',
+      menuWidth: 220,
+      menuHeight: 160,
+      viewportWidth: 1000,
+      viewportHeight: 800,
+      widthMode: 'intrinsic',
+    })
+
+    expect(layout.left).toBeLessThanOrEqual(1000 - 220 - 8)
+    expect(layout.width).toBeUndefined()
+  })
+
+  it('keeps menubar menus flush with the bar', () => {
+    const layout = resolveMenuViewportLayout({
+      anchorRect: {
+        top: 0,
+        bottom: 28,
+        left: 120,
+        right: 180,
+        width: 60,
+      },
+      preferredTop: 28,
+      preferredLeft: 120,
+      placement: 'below-menubar-start',
+      menuWidth: 220,
+      menuHeight: 160,
+      viewportWidth: 1000,
+      viewportHeight: 800,
+    })
+
+    expect(layout.top).toBe(28)
+  })
+
+  it('sets width for anchor mode menus', () => {
+    const layout = resolveMenuViewportLayout({
+      anchorRect: {
+        top: 40,
+        bottom: 68,
+        left: 120,
+        right: 220,
+        width: 100,
+      },
+      preferredTop: 72,
+      preferredLeft: 120,
+      placement: 'below-start',
+      menuWidth: 100,
+      menuHeight: 120,
+      viewportWidth: 1000,
+      viewportHeight: 800,
+      widthMode: 'anchor',
+    })
+
+    expect(layout.width).toBeGreaterThanOrEqual(120)
+  })
+
+  it('opens above the anchor when there is more space above', () => {
+    const layout = resolveMenuViewportLayout({
+      anchorRect: {
+        top: 720,
+        bottom: 748,
+        left: 120,
+        right: 220,
+        width: 100,
+      },
+      preferredTop: 752,
+      preferredLeft: 120,
+      placement: 'below-start',
+      menuWidth: 200,
+      menuHeight: 220,
+      viewportWidth: 1000,
+      viewportHeight: 760,
+    })
+
+    expect(layout.top).toBeLessThan(720)
+  })
+
+  it('opens above-start menus upward from the anchor', () => {
+    const layout = resolveMenuViewportLayout({
+      anchorRect: {
+        top: 720,
+        bottom: 748,
+        left: 120,
+        right: 220,
+        width: 100,
+      },
+      preferredTop: 716,
+      preferredLeft: 120,
+      placement: 'above-start',
+      menuWidth: 200,
+      menuHeight: 180,
+      viewportWidth: 1000,
+      viewportHeight: 760,
+    })
+
+    expect(layout.top).toBeLessThan(720)
+    expect(layout.top + layout.maxHeight).toBeLessThanOrEqual(720)
+  })
+
+  it('limits menu height to the remaining viewport space', () => {
+    const layout = resolveMenuViewportLayout({
+      anchorRect: {
+        top: 40,
+        bottom: 68,
+        left: 40,
+        right: 180,
+        width: 140,
+      },
+      preferredTop: 72,
+      preferredLeft: 40,
+      placement: 'below-start',
+      menuWidth: 200,
+      menuHeight: 400,
+      viewportWidth: 1000,
+      viewportHeight: 300,
+      maxHeight: 280,
+    })
+
+    expect(layout.maxHeight).toBeLessThanOrEqual(280)
+    expect(layout.top + layout.maxHeight).toBeLessThanOrEqual(300)
+  })
+})

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

@@ -0,0 +1,122 @@
+import type { MenuPlacement } from './useMenuAnchorPosition.js'
+
+export const MENU_VIEWPORT_MARGIN_PX = 8
+export const MENU_ANCHOR_GAP_PX = 4
+export const MENU_INTRINSIC_MIN_WIDTH_PX = 220
+export const MENU_ANCHOR_MIN_WIDTH_PX = 120
+export const MENU_DEFAULT_MAX_HEIGHT_PX = 320
+
+/** How the portaled menu sizes horizontally. */
+export type MenuWidthMode = 'intrinsic' | 'anchor'
+
+export interface ResolvedMenuLayout {
+  top: number
+  left: number
+  maxHeight: number
+  /** Set only for `anchor` width mode. */
+  width?: number
+}
+
+export interface ResolveMenuViewportLayoutArgs {
+  anchorRect: Pick<DOMRect, 'top' | 'bottom' | 'left' | 'right' | 'width'>
+  preferredTop: number
+  preferredLeft: number
+  placement: MenuPlacement
+  menuWidth: number
+  menuHeight: number
+  viewportWidth?: number
+  viewportHeight?: number
+  widthMode?: MenuWidthMode
+  minWidth?: number
+  maxHeight?: number
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max)
+}
+
+/** Clamp and flip a menu position computed by `useMenuAnchorPosition`. */
+export function resolveMenuViewportLayout({
+  anchorRect,
+  preferredTop,
+  preferredLeft,
+  placement,
+  menuWidth,
+  menuHeight,
+  viewportWidth = typeof window !== 'undefined' ? window.innerWidth : 0,
+  viewportHeight = typeof window !== 'undefined' ? window.innerHeight : 0,
+  widthMode = 'intrinsic',
+  minWidth,
+  maxHeight = MENU_DEFAULT_MAX_HEIGHT_PX,
+}: ResolveMenuViewportLayoutArgs): ResolvedMenuLayout {
+  const margin = MENU_VIEWPORT_MARGIN_PX
+  const gap = MENU_ANCHOR_GAP_PX
+  const maxViewportWidth = Math.max(0, viewportWidth - margin * 2)
+
+  const resolvedMinWidth =
+    minWidth ??
+    (widthMode === 'anchor'
+      ? MENU_ANCHOR_MIN_WIDTH_PX
+      : MENU_INTRINSIC_MIN_WIDTH_PX)
+
+  const layoutWidth =
+    widthMode === 'anchor'
+      ? clamp(
+          Math.max(anchorRect.width, resolvedMinWidth),
+          resolvedMinWidth,
+          maxViewportWidth,
+        )
+      : clamp(
+          Math.max(menuWidth, resolvedMinWidth),
+          resolvedMinWidth,
+          maxViewportWidth,
+        )
+
+  let left = clamp(
+    preferredLeft,
+    margin,
+    Math.max(margin, viewportWidth - layoutWidth - margin),
+  )
+
+  let top = preferredTop
+
+  if (placement === 'above-start') {
+    top = anchorRect.top - gap - menuHeight
+    const spaceAbove = Math.max(0, anchorRect.top - gap - margin)
+    const spaceBelow = Math.max(
+      0,
+      viewportHeight - anchorRect.bottom - gap - margin,
+    )
+    if (menuHeight > spaceAbove && spaceBelow > spaceAbove) {
+      top = anchorRect.bottom + gap
+    }
+  } else if (
+    placement === 'below-start' ||
+    placement === 'below-menubar-start' ||
+    placement === 'at-point'
+  ) {
+    const opensBelow = preferredTop >= anchorRect.bottom - 0.5
+    if (opensBelow) {
+      const spaceBelow = Math.max(0, viewportHeight - preferredTop - margin)
+      const spaceAbove = Math.max(0, anchorRect.top - gap - margin)
+      if (menuHeight > spaceBelow && spaceAbove > spaceBelow) {
+        top = anchorRect.top - gap - menuHeight
+      }
+    }
+  }
+
+  top = clamp(top, margin, Math.max(margin, viewportHeight - margin))
+
+  const opensAboveAnchor = top < anchorRect.top
+  const availableHeight = opensAboveAnchor
+    ? Math.max(0, anchorRect.top - gap - top)
+    : Math.max(0, viewportHeight - top - margin)
+  const resolvedMaxHeight = Math.min(maxHeight, availableHeight)
+
+  return {
+    top,
+    left,
+    maxHeight: resolvedMaxHeight,
+    ...(widthMode === 'anchor' ? { width: layoutWidth } : {}),
+  }
+}

package/src/components/common/dropdown/selectMenuLayout.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest'
+import { MENU_ANCHOR_GAP_PX } from './menuViewportPosition.js'
+import { resolveSelectMenuLayout } from './selectMenuLayout.js'
+
+describe('resolveSelectMenuLayout', () => {
+  it('opens below the anchor by default', () => {
+    const layout = resolveSelectMenuLayout({
+      anchorRect: { top: 100, bottom: 128, left: 40, right: 180, width: 140 },
+      placement: 'below',
+      viewportWidth: 1000,
+      viewportHeight: 800,
+    })
+
+    expect(layout.resolvedPlacement).toBe('below')
+    expect(layout.top).toBe(128)
+    expect(layout.bottom).toBeUndefined()
+  })
+
+  it('opens above the anchor when requested', () => {
+    const layout = resolveSelectMenuLayout({
+      anchorRect: { top: 720, bottom: 748, left: 40, right: 180, width: 140 },
+      placement: 'above',
+      viewportWidth: 1000,
+      viewportHeight: 800,
+    })
+
+    expect(layout.resolvedPlacement).toBe('above')
+    expect(layout.bottom).toBe(800 - 720)
+    expect(layout.top).toBeUndefined()
+  })
+
+  it('auto prefers above when there is more space above', () => {
+    const layout = resolveSelectMenuLayout({
+      anchorRect: { top: 720, bottom: 748, left: 40, right: 180, width: 140 },
+      placement: 'auto',
+      viewportWidth: 1000,
+      viewportHeight: 800,
+    })
+
+    expect(layout.resolvedPlacement).toBe('above')
+  })
+})

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

@@ -0,0 +1,123 @@
+import {
+  MENU_ANCHOR_GAP_PX,
+  MENU_VIEWPORT_MARGIN_PX,
+} from './menuViewportPosition.js'
+
+export const SELECT_MENU_INTRINSIC_MIN_WIDTH_PX = 220
+export const SELECT_MENU_ANCHOR_MIN_WIDTH_PX = 120
+export const SELECT_MENU_DEFAULT_MIN_HEIGHT_PX = 120
+
+export type SelectMenuPlacement = 'below' | 'above' | 'auto'
+export type SelectMenuResolvedPlacement = 'below' | 'above'
+export type SelectMenuWidthMode = 'intrinsic' | 'anchor'
+export type SelectMenuPanelVariant =
+  | 'default'
+  | 'quiet'
+  | 'palette'
+  | 'workspace'
+
+export interface SelectMenuLayoutInput {
+  anchorRect: Pick<DOMRect, 'top' | 'bottom' | 'left' | 'right' | 'width'>
+  placement: SelectMenuPlacement
+  widthMode?: SelectMenuWidthMode
+  minWidth?: number
+  /** When true (default), menu border sits flush on the anchor edge. */
+  attachToAnchor?: boolean
+  viewportWidth?: number
+  viewportHeight?: number
+}
+
+export interface SelectMenuLayout {
+  left: number
+  resolvedPlacement: SelectMenuResolvedPlacement
+  top?: number
+  bottom?: number
+  maxHeight: number
+  minWidth: number
+  width?: number
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max)
+}
+
+export function resolveSelectMenuLayout({
+  anchorRect,
+  placement,
+  widthMode = 'intrinsic',
+  minWidth,
+  attachToAnchor = true,
+  viewportWidth = typeof window !== 'undefined' ? window.innerWidth : 0,
+  viewportHeight = typeof window !== 'undefined' ? window.innerHeight : 0,
+}: SelectMenuLayoutInput): SelectMenuLayout {
+  const margin = MENU_VIEWPORT_MARGIN_PX
+  const gap = attachToAnchor ? 0 : MENU_ANCHOR_GAP_PX
+  const maxViewportWidth = Math.max(0, viewportWidth - margin * 2)
+
+  const resolvedMinWidth =
+    minWidth ??
+    (widthMode === 'anchor'
+      ? SELECT_MENU_ANCHOR_MIN_WIDTH_PX
+      : SELECT_MENU_INTRINSIC_MIN_WIDTH_PX)
+
+  const layoutWidth =
+    widthMode === 'anchor'
+      ? clamp(
+          Math.max(anchorRect.width, resolvedMinWidth),
+          resolvedMinWidth,
+          maxViewportWidth,
+        )
+      : clamp(resolvedMinWidth, resolvedMinWidth, maxViewportWidth)
+
+  const spaceBelow = Math.max(
+    0,
+    viewportHeight - anchorRect.bottom - gap - margin,
+  )
+  const spaceAbove = Math.max(0, anchorRect.top - gap - margin)
+
+  let resolvedPlacement: SelectMenuResolvedPlacement =
+    placement === 'above'
+      ? 'above'
+      : placement === 'below'
+      ? 'below'
+      : spaceBelow >= spaceAbove
+      ? 'below'
+      : 'above'
+
+  const left = clamp(
+    anchorRect.left,
+    margin,
+    Math.max(margin, viewportWidth - layoutWidth - margin),
+  )
+
+  if (resolvedPlacement === 'below') {
+    const top = anchorRect.bottom + gap
+    const maxHeight = Math.max(
+      SELECT_MENU_DEFAULT_MIN_HEIGHT_PX,
+      viewportHeight - top - margin,
+    )
+    return {
+      left,
+      resolvedPlacement,
+      top,
+      maxHeight,
+      minWidth: layoutWidth,
+      ...(widthMode === 'anchor' ? { width: layoutWidth } : {}),
+    }
+  }
+
+  const bottom = viewportHeight - anchorRect.top + gap
+  const maxHeight = Math.max(
+    SELECT_MENU_DEFAULT_MIN_HEIGHT_PX,
+    anchorRect.top - gap - margin,
+  )
+
+  return {
+    left,
+    resolvedPlacement,
+    bottom,
+    maxHeight,
+    minWidth: layoutWidth,
+    ...(widthMode === 'anchor' ? { width: layoutWidth } : {}),
+  }
+}

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

@@ -0,0 +1,109 @@
+import { useCallback, useLayoutEffect, useState, type RefObject } from 'react'
+import { MENU_ANCHOR_GAP_PX } from './menuViewportPosition.js'
+
+export type MenuPlacement =
+  | 'below-start'
+  | 'above-start'
+  | 'below-menubar-start'
+  | 'after-start'
+  | 'at-point'
+
+export interface MenuAnchorPosition {
+  top: number
+  left: number
+}
+
+export interface UseMenuAnchorPositionArgs {
+  /** Primary anchor (trigger row, menubar, or point anchor for `at-point`). */
+  anchorRef: RefObject<HTMLElement | null>
+  /** Horizontal align for `below-menubar-start` (section trigger). */
+  alignRef?: RefObject<HTMLElement | null>
+  active: boolean
+  placement: MenuPlacement
+  /** Screen coordinates for `at-point`. */
+  point?: { x: number; y: number } | null
+}
+
+/** @param active When false, position updates stop (use portal `mounted`, not raw `open`). */
+export function useMenuAnchorPosition({
+  anchorRef,
+  alignRef,
+  active,
+  placement,
+  point,
+}: UseMenuAnchorPositionArgs): MenuAnchorPosition | null {
+  const [position, setPosition] = useState<MenuAnchorPosition | null>(null)
+
+  const update = useCallback(() => {
+    if (placement === 'at-point') {
+      if (!point) {
+        setPosition(null)
+        return
+      }
+      setPosition({
+        top: point.y + MENU_ANCHOR_GAP_PX,
+        left: point.x,
+      })
+      return
+    }
+
+    const anchor = anchorRef.current
+    if (!anchor) {
+      setPosition(null)
+      return
+    }
+
+    if (placement === 'below-menubar-start') {
+      const align = alignRef?.current
+      if (!align) {
+        setPosition(null)
+        return
+      }
+      const rowRect = anchor.getBoundingClientRect()
+      const alignRect = align.getBoundingClientRect()
+      setPosition({
+        top: rowRect.bottom,
+        left: alignRect.left,
+      })
+      return
+    }
+
+    const rect = anchor.getBoundingClientRect()
+    if (placement === 'below-start') {
+      setPosition({
+        top: rect.bottom + MENU_ANCHOR_GAP_PX,
+        left: rect.left,
+      })
+      return
+    }
+
+    if (placement === 'above-start') {
+      setPosition({
+        top: rect.top - MENU_ANCHOR_GAP_PX,
+        left: rect.left,
+      })
+      return
+    }
+
+    setPosition({
+      top: rect.top,
+      left: rect.right + MENU_ANCHOR_GAP_PX,
+    })
+  }, [anchorRef, alignRef, placement, point])
+
+  useLayoutEffect(() => {
+    if (!active) {
+      setPosition(null)
+      return
+    }
+    update()
+    window.addEventListener('resize', update)
+    window.addEventListener('scroll', update, true)
+    return () => {
+      window.removeEventListener('resize', update)
+      window.removeEventListener('scroll', update, true)
+    }
+  }, [active, update])
+
+  return active ? position : null
+}

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

@@ -0,0 +1,30 @@
+import { useCallback, useRef, useState, type RefObject } from 'react'
+
+export interface UseSelectMenuAnchorOptions {
+  disabled?: boolean
+}
+
+export interface UseSelectMenuAnchorResult<
+  T extends HTMLElement = HTMLElement,
+> {
+  anchorRef: RefObject<T | null>
+  open: boolean
+  close: () => void
+  toggle: () => void
+  setOpen: (open: boolean) => void
+}
+
+export function useSelectMenuAnchor<T extends HTMLElement = HTMLElement>({
+  disabled = false,
+}: UseSelectMenuAnchorOptions = {}): UseSelectMenuAnchorResult<T> {
+  const anchorRef = useRef<T | null>(null)
+  const [open, setOpen] = useState(false)
+
+  const close = useCallback(() => setOpen(false), [])
+  const toggle = useCallback(() => {
+    if (disabled) return
+    setOpen(current => !current)
+  }, [disabled])
+
+  return { anchorRef, open, close, toggle, setOpen }
+}