aeon-ui-engine 1.5.1 → 1.9.0

package/packages/react/src/clipboard/index.tsx

@@ -0,0 +1,117 @@
+import { clipboardAnatomy, partAttrs, partOnlyAttrs } from '@aeon-ui/core'
+import { clipboardMachine, type ClipboardStatus } from '@aeon-ui/primitives'
+import {
+  createContext,
+  forwardRef,
+  useContext,
+  useMemo,
+  type ButtonHTMLAttributes,
+  type CSSProperties,
+  type HTMLAttributes,
+  type MouseEvent,
+  type ReactNode,
+} from 'react'
+import { useAeonMachine } from '../hooks/use-aeon-machine.js'
+import { mergeProps } from '../utils/merge-props.js'
+
+interface ClipboardContextValue {
+  status: ClipboardStatus
+  copy: () => void
+}
+
+const ClipboardCtx = createContext<ClipboardContextValue | null>(null)
+
+function useClipboardCtx() {
+  const ctx = useContext(ClipboardCtx)
+  if (!ctx) throw new Error('Clipboard parts must be used within Clipboard.Root')
+  return ctx
+}
+
+/** Read the copy status from any part inside Clipboard.Root. */
+export const useClipboardStatus = () => useClipboardCtx().status
+
+const visuallyHidden: CSSProperties = {
+  position: 'absolute',
+  width: 1,
+  height: 1,
+  margin: -1,
+  padding: 0,
+  overflow: 'hidden',
+  clip: 'rect(0 0 0 0)',
+  whiteSpace: 'nowrap',
+  border: 0,
+}
+
+const ANNOUNCE: Partial<Record<ClipboardStatus, string>> = { copied: 'Copied', failed: 'Copy failed' }
+
+export interface ClipboardRootProps extends HTMLAttributes<HTMLDivElement> {
+  /** Text written to the clipboard; read at the moment of copying. */
+  value: string
+  /** How long copied / failed show, in ms. */
+  timeout?: number
+}
+
+const Root = forwardRef<HTMLDivElement, ClipboardRootProps>(function ClipboardRoot(
+  { value, timeout, children, ...rest },
+  ref,
+) {
+  const [snapshot, send] = useAeonMachine(clipboardMachine, { input: { timeout } })
+  const status = snapshot.value as ClipboardStatus
+  const ctx = useMemo(() => ({ status, copy: () => send({ type: 'COPY', value }) }), [status, send, value])
+
+  return (
+    <ClipboardCtx.Provider value={ctx}>
+      <div ref={ref} {...mergeProps(partAttrs(clipboardAnatomy.scope, clipboardAnatomy.root, { state: status }), rest)}>
+        {children}
+        <span role="status" style={visuallyHidden} {...partOnlyAttrs(clipboardAnatomy.status)}>
+          {ANNOUNCE[status] ?? ''}
+        </span>
+      </div>
+    </ClipboardCtx.Provider>
+  )
+})
+
+const Trigger = forwardRef<HTMLButtonElement, ButtonHTMLAttributes<HTMLButtonElement>>(function ClipboardTrigger(
+  { onClick, ...rest },
+  ref,
+) {
+  const { status, copy } = useClipboardCtx()
+
+  return (
+    <button
+      ref={ref}
+      type="button"
+      aria-label="Copy"
+      {...mergeProps(
+        partOnlyAttrs(clipboardAnatomy.trigger, { state: status }),
+        {
+          onClick: (e: MouseEvent<HTMLButtonElement>) => {
+            onClick?.(e)
+            if (!e.defaultPrevented) copy()
+          },
+        },
+        rest,
+      )}
+    />
+  )
+})
+
+export interface ClipboardIndicatorProps extends HTMLAttributes<HTMLSpanElement> {
+  /** Shown while copied; `children` show otherwise. */
+  copied?: ReactNode
+}
+
+const Indicator = forwardRef<HTMLSpanElement, ClipboardIndicatorProps>(function ClipboardIndicator(
+  { copied, children, ...rest },
+  ref,
+) {
+  const { status } = useClipboardCtx()
+
+  return (
+    <span ref={ref} aria-hidden {...mergeProps(partOnlyAttrs(clipboardAnatomy.indicator, { state: status }), rest)}>
+      {status === 'copied' && copied !== undefined ? copied : children}
+    </span>
+  )
+})
+
+export const Clipboard = { Root, Trigger, Indicator }

package/packages/react/src/composer/index.tsx

@@ -7,6 +7,7 @@ import {
   type ReactNode,
   type TextareaHTMLAttributes,
 } from 'react'
+import { rowLimits, useAutoGrow } from '../textarea/index.js'
 import { mergeProps } from '../utils/merge-props.js'
 
 /**
@@ -48,13 +49,21 @@ const Root = forwardRef<HTMLFormElement, ComposerRootProps>(function ComposerRoo
   )
 })
 
-const Input = forwardRef<HTMLTextAreaElement, TextareaHTMLAttributes<HTMLTextAreaElement>>(
-  function ComposerInput(props, ref) {
+export interface ComposerInputProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
+  /** Height floor in lines (default 1). */
+  minRows?: number
+  /** Height ceiling in lines before the input scrolls (default 4). */
+  maxRows?: number
+}
+
+const Input = forwardRef<HTMLTextAreaElement, ComposerInputProps>(
+  function ComposerInput({ minRows, maxRows, style, ...props }, ref) {
+    const grow = useAutoGrow(ref, props.value)
     return (
       <textarea
-        ref={ref}
-        rows={1}
-        {...mergeProps(partAttrs(composerAnatomy.scope, composerAnatomy.input), props)}
+        rows={minRows ?? 1}
+        style={{ ...rowLimits(minRows, maxRows), ...style }}
+        {...mergeProps(partAttrs(composerAnatomy.scope, composerAnatomy.input), grow, props)}
       />
     )
   },

package/packages/react/src/dialog/index.tsx

@@ -52,12 +52,20 @@ const Root = forwardRef<HTMLDivElement, DialogRootProps>(function DialogRoot(
     input: { open: defaultOpen },
   })
 
-  const resolvedOpen = open ?? snapshot.context.open
+  const machineOpen = snapshot.context.open
+  const resolvedOpen = open ?? machineOpen
   const contentRef = useRef<HTMLDivElement>(null)
 
+  /**
+   * Report the machine's intent, not the resolved value: a controlled owner
+   * holding `open` would otherwise never hear about its own trigger or escape.
+   */
+  const reportedOpen = useRef(machineOpen)
   useEffect(() => {
-    onOpenChange?.(resolvedOpen)
-  }, [resolvedOpen, onOpenChange])
+    if (reportedOpen.current === machineOpen) return
+    reportedOpen.current = machineOpen
+    onOpenChange?.(machineOpen)
+  }, [machineOpen, onOpenChange])
 
   useEffect(() => {
     if (open !== undefined) {

package/packages/react/src/floating/FloatingPositioner.tsx

@@ -10,6 +10,15 @@ export interface FloatingPositionerProps extends HTMLAttributes<HTMLDivElement>
   part: string
   triggerRef: RefObject<HTMLElement | null>
   positionerRef: RefObject<HTMLDivElement | null>
+  /**
+   * Position against this element instead of the trigger.
+   *
+   * A trigger is often a small icon button pinned to one edge of a much larger
+   * region. Aligning to the button then throws a wide surface off-screen, and
+   * clamping only slides it back to the viewport edge. Anchoring to the region
+   * the surface belongs to puts it where the eye already is.
+   */
+  anchorRef?: RefObject<HTMLElement | null>
   portalled?: boolean
   placement?: AnchorPlacement
   matchAnchorWidth?: boolean
@@ -28,6 +37,7 @@ export const FloatingPositioner = forwardRef<HTMLDivElement, FloatingPositionerP
       part,
       triggerRef,
       positionerRef,
+      anchorRef,
       portalled = true,
       placement = 'bottom-start',
       matchAnchorWidth = false,
@@ -40,7 +50,7 @@ export const FloatingPositioner = forwardRef<HTMLDivElement, FloatingPositionerP
     ref,
   ) {
     const mounted = usePortalledMount()
-    useAnchorPosition(triggerRef, positionerRef, open && portalled, placement, {
+    useAnchorPosition(anchorRef ?? triggerRef, positionerRef, open && portalled, placement, {
       matchWidth: matchAnchorWidth,
       gutter,
       zIndex,

package/packages/react/src/index.ts

@@ -6,6 +6,10 @@ export * from './prompt/index.js'
 export * from './status-banner/index.js'
 export * from './tabs/index.js'
 export * from './separator/index.js'
+export * from './prose/index.js'
+export * from './textarea/index.js'
+export * from './segment-group/index.js'
+export * from './clipboard/index.js'
 export * from './progress/index.js'
 export * from './radio-group/index.js'
 export * from './slider/index.js'

package/packages/react/src/menu/index.tsx

@@ -51,16 +51,21 @@ const Root = forwardRef<HTMLDivElement, MenuRootProps>(function MenuRoot(
   ref,
 ) {
   const [snapshot, send] = useAeonMachine(popoverMachine, { input: { open: defaultOpen } })
-  const resolvedOpen = open ?? snapshot.context.open
+  const machineOpen = snapshot.context.open
+  const resolvedOpen = open ?? machineOpen
   const rootRef = useRef<HTMLDivElement>(null)
   const triggerRef = useRef<HTMLButtonElement>(null)
   const positionerRef = useRef<HTMLDivElement>(null)
   const triggerId = useId()
   const menuId = useId()
 
+  /** Machine intent, so a controlled owner still hears its own trigger. */
+  const reportedOpen = useRef(machineOpen)
   useEffect(() => {
-    onOpenChange?.(resolvedOpen)
-  }, [resolvedOpen, onOpenChange])
+    if (reportedOpen.current === machineOpen) return
+    reportedOpen.current = machineOpen
+    onOpenChange?.(machineOpen)
+  }, [machineOpen, onOpenChange])
 
   useEffect(() => {
     if (open !== undefined) send({ type: 'SET_OPEN', open })

package/packages/react/src/popover/index.tsx

@@ -53,16 +53,21 @@ const Root = forwardRef<HTMLDivElement, PopoverRootProps>(function PopoverRoot(
   const [snapshot, send] = useAeonMachine(popoverMachine, {
     input: { open: defaultOpen },
   })
-  const resolvedOpen = open ?? snapshot.context.open
+  const machineOpen = snapshot.context.open
+  const resolvedOpen = open ?? machineOpen
   const rootRef = useRef<HTMLDivElement>(null)
   const triggerRef = useRef<HTMLButtonElement>(null)
   const positionerRef = useRef<HTMLDivElement>(null)
   const triggerId = useId()
   const contentId = useId()
 
+  /** Machine intent, so a controlled owner still hears its own trigger. */
+  const reportedOpen = useRef(machineOpen)
   useEffect(() => {
-    onOpenChange?.(resolvedOpen)
-  }, [resolvedOpen, onOpenChange])
+    if (reportedOpen.current === machineOpen) return
+    reportedOpen.current = machineOpen
+    onOpenChange?.(machineOpen)
+  }, [machineOpen, onOpenChange])
 
   useEffect(() => {
     if (open !== undefined) send({ type: 'SET_OPEN', open })
@@ -132,6 +137,10 @@ export interface PopoverPositionerProps extends HTMLAttributes<HTMLDivElement> {
   /** Mount panel in document.body (default true). */
   portalled?: boolean
   placement?: AnchorPlacement
+  /** Align to this region rather than the trigger. See `FloatingPositioner`. */
+  anchorRef?: React.RefObject<HTMLElement | null>
+  /** Size the panel to the anchor, so it spans the region it belongs to. */
+  matchAnchorWidth?: boolean
   /** Gap between trigger and panel (default 4). */
   gutter?: number
   /** Stack level for the portalled surface (default 50). */
@@ -140,7 +149,17 @@ export interface PopoverPositionerProps extends HTMLAttributes<HTMLDivElement> {
 }
 
 const Positioner = forwardRef<HTMLDivElement, PopoverPositionerProps>(function PopoverPositioner(
-  { portalled = true, placement = 'bottom-start', gutter, zIndex, children, className, ...rest },
+  {
+    portalled = true,
+    placement = 'bottom-start',
+    anchorRef,
+    matchAnchorWidth = false,
+    gutter,
+    zIndex,
+    children,
+    className,
+    ...rest
+  },
   ref,
 ) {
   const { open, triggerRef, positionerRef } = usePopoverCtx()
@@ -153,6 +172,8 @@ const Positioner = forwardRef<HTMLDivElement, PopoverPositionerProps>(function P
       part={popoverAnatomy.positioner}
       triggerRef={triggerRef}
       positionerRef={positionerRef}
+      anchorRef={anchorRef}
+      matchAnchorWidth={matchAnchorWidth}
       portalled={portalled}
       placement={placement}
       gutter={gutter}

package/packages/react/src/prose/index.tsx

@@ -0,0 +1,11 @@
+import { partAttrs, proseAnatomy } from '@aeon-ui/core'
+import { forwardRef, type HTMLAttributes } from 'react'
+import { mergeProps } from '../utils/merge-props.js'
+
+export type ProseRootProps = HTMLAttributes<HTMLDivElement>
+
+const Root = forwardRef<HTMLDivElement, ProseRootProps>(function ProseRoot(props, ref) {
+  return <div ref={ref} {...mergeProps(partAttrs(proseAnatomy.scope, proseAnatomy.root), props)} />
+})
+
+export const Prose = { Root }

package/packages/react/src/radio-group/index.tsx

@@ -43,7 +43,8 @@ function useRadioGroupItemCtx() {
   return ctx
 }
 
-export interface RadioGroupRootProps {
+export interface RadioGroupRootProps
+  extends Omit<HTMLAttributes<HTMLDivElement>, 'defaultValue' | 'onChange' | 'children'> {
   value?: string
   defaultValue?: string
   onValueChange?: (value: string) => void

package/packages/react/src/scroll/index.tsx

@@ -96,3 +96,4 @@ export const Scroll = {
 }
 
 export { useScrollState } from './use-scroll-state.js'
+export { useWindowedRange, type UseWindowedRangeOptions } from './use-windowed-range.js'

package/packages/react/src/scroll/use-windowed-range.ts

@@ -0,0 +1,118 @@
+import {
+  computeListWindow,
+  fullListWindow,
+  LIST_WINDOW_MIN_ITEMS,
+  measureListColumns,
+  measureListRowExtent,
+  resolveScrollRoot,
+  sameListWindow,
+  scrollRootExtent,
+  scrollRootScrolledPast,
+  type ListWindow,
+  type ListWindowAxis,
+} from '@aeon-ui/core'
+import { useLayoutEffect, useState, type RefObject } from 'react'
+
+export interface UseWindowedRangeOptions {
+  total: number
+  /** Fallback row pitch, used until a row can be measured. */
+  itemExtent: number
+  /** Fallback column count for grids; the real count is read from the grid. */
+  columns?: number
+  overscan?: number
+  /** Restrict measuring to real rows when the list also holds other chrome. */
+  rowSelector?: string
+  minItems?: number
+  /** `x` windows a horizontal strip by item width; columns do not apply. */
+  axis?: ListWindowAxis
+  /** The list element itself; its scrollable ancestor drives the window. */
+  scrollRef: RefObject<HTMLElement | null>
+}
+
+function hintedWindow(o: UseWindowedRangeOptions): ListWindow {
+  return computeListWindow({
+    total: o.total,
+    rowExtent: o.itemExtent,
+    columns: o.axis === 'x' ? 1 : o.columns,
+    overscan: o.overscan,
+    scrolledPast: 0,
+    viewportHeight: typeof window === 'undefined' ? 0 : o.axis === 'x' ? window.innerWidth : window.innerHeight,
+    minItems: o.minItems,
+  })
+}
+
+/**
+ * Windowed slice for long lists and grids. Render `items.slice(start, end)`
+ * between spacers of `padStart` / `padEnd` (spread `listWindowPadAttrs`) or
+ * as list padding; each row keeps its own data-aeon-* projection.
+ *
+ * The first render windows from the hints, so a long list never mounts whole.
+ * Measuring reads layout, so it runs at most once per frame, and the window is
+ * published only when it moves: a scroll inside the current window renders
+ * nothing.
+ */
+export function useWindowedRange(options: UseWindowedRangeOptions): ListWindow {
+  const {
+    total,
+    itemExtent,
+    columns = 1,
+    overscan = 8,
+    rowSelector,
+    minItems = LIST_WINDOW_MIN_ITEMS,
+    axis = 'y',
+    scrollRef,
+  } = options
+  const [range, setRange] = useState<ListWindow>(() => hintedWindow(options))
+
+  useLayoutEffect(() => {
+    const keep = (next: ListWindow) => setRange((current) => (sameListWindow(current, next) ? current : next))
+    if (total < minItems) {
+      keep(fullListWindow(total))
+      return
+    }
+    const list = scrollRef.current
+    if (!list) {
+      keep(hintedWindow({ total, itemExtent, columns, overscan, minItems, axis, scrollRef }))
+      return
+    }
+    const root = resolveScrollRoot(list, axis)
+    let frame = 0
+    let cancelled = false
+
+    const measureNow = () => {
+      const style = getComputedStyle(list)
+      keep(
+        computeListWindow({
+          total,
+          rowExtent: measureListRowExtent(list, style, itemExtent, rowSelector, axis),
+          columns: axis === 'x' ? 1 : measureListColumns(style, columns),
+          overscan,
+          scrolledPast: scrollRootScrolledPast(root, list, axis),
+          viewportHeight: scrollRootExtent(root, axis),
+          minItems,
+        }),
+      )
+    }
+
+    const measure = () => {
+      if (cancelled || frame) return
+      frame = window.requestAnimationFrame(() => {
+        frame = 0
+        if (!cancelled) measureNow()
+      })
+    }
+
+    measureNow()
+    const target: EventTarget = root === window ? window : root
+    target.addEventListener('scroll', measure, { passive: true })
+    window.addEventListener('resize', measure)
+    return () => {
+      cancelled = true
+      window.cancelAnimationFrame(frame)
+      target.removeEventListener('scroll', measure)
+      window.removeEventListener('resize', measure)
+    }
+  }, [total, itemExtent, columns, overscan, rowSelector, minItems, axis, scrollRef])
+
+  return range
+}

package/packages/react/src/segment-group/index.tsx

@@ -0,0 +1,171 @@
+import { partAttrs, partOnlyAttrs, segmentGroupAnatomy } from '@aeon-ui/core'
+import { tabsMachine } from '@aeon-ui/primitives'
+import {
+  createContext,
+  forwardRef,
+  useCallback,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ButtonHTMLAttributes,
+  type HTMLAttributes,
+  type KeyboardEvent,
+  type MouseEvent,
+} from 'react'
+import { useAeonMachine } from '../hooks/use-aeon-machine.js'
+import { assignRef } from '../utils/assign-ref.js'
+import { mergeProps } from '../utils/merge-props.js'
+
+interface SegmentGroupContextValue {
+  value: string
+  disabled: boolean
+  /** The one item Tab lands on: the selected item, or the first enabled one when that is missing or disabled. */
+  tabStop: string | null
+  selectValue: (next: string) => void
+}
+
+const SegmentGroupCtx = createContext<SegmentGroupContextValue | null>(null)
+
+function useSegmentGroupCtx() {
+  const ctx = useContext(SegmentGroupCtx)
+  if (!ctx) throw new Error('SegmentGroup parts must be used within SegmentGroup.Root')
+  return ctx
+}
+
+const ROOT = `[data-aeon-scope="${segmentGroupAnatomy.scope}"]`
+
+/** This group's enabled items in DOM order, leaving out items of nested groups. */
+function enabledItems(root: HTMLElement): HTMLButtonElement[] {
+  return Array.from(
+    root.querySelectorAll<HTMLButtonElement>(`[data-aeon-part="${segmentGroupAnatomy.item}"]:not(:disabled)`),
+  ).filter((item) => item.closest(ROOT) === root)
+}
+
+export interface SegmentGroupRootProps extends Omit<HTMLAttributes<HTMLDivElement>, 'defaultValue' | 'onChange'> {
+  value?: string
+  defaultValue?: string
+  onValueChange?: (value: string) => void
+  disabled?: boolean
+  orientation?: 'horizontal' | 'vertical'
+}
+
+const Root = forwardRef<HTMLDivElement, SegmentGroupRootProps>(function SegmentGroupRoot(
+  { value, defaultValue = '', onValueChange, disabled = false, orientation = 'horizontal', ...rest },
+  ref,
+) {
+  const [snapshot, send] = useAeonMachine(tabsMachine, {
+    input: { value: value ?? defaultValue, disabled },
+  })
+  const controlled = value !== undefined
+  const resolvedValue = value ?? snapshot.context.value
+
+  useEffect(() => {
+    if (controlled) send({ type: 'SET_VALUE', value })
+  }, [controlled, value, send])
+
+  const selectValue = useCallback(
+    (next: string) => {
+      if (disabled || next === resolvedValue) return
+      if (!controlled) send({ type: 'SELECT', value: next })
+      onValueChange?.(next)
+    },
+    [disabled, resolvedValue, controlled, send, onValueChange],
+  )
+
+  const node = useRef<HTMLDivElement | null>(null)
+  const setRef = useCallback(
+    (el: HTMLDivElement | null) => {
+      node.current = el
+      assignRef(ref, el)
+    },
+    [ref],
+  )
+
+  /* Items can be added, removed or disabled at any render, so the tab stop is re-read from the DOM each time. */
+  const [tabStop, setTabStop] = useState<string | null>(null)
+  useLayoutEffect(() => {
+    const items = node.current ? enabledItems(node.current) : []
+    const next = (items.find((item) => item.dataset.value === resolvedValue) ?? items[0])?.dataset.value ?? null
+    setTabStop((prev) => (prev === next ? prev : next))
+  })
+
+  const ctx = useMemo(
+    () => ({ value: resolvedValue, disabled, tabStop, selectValue }),
+    [resolvedValue, disabled, tabStop, selectValue],
+  )
+
+  return (
+    <SegmentGroupCtx.Provider value={ctx}>
+      <div
+        ref={setRef}
+        role="radiogroup"
+        aria-orientation={orientation}
+        aria-disabled={disabled || undefined}
+        data-orientation={orientation}
+        {...mergeProps(partAttrs(segmentGroupAnatomy.scope, segmentGroupAnatomy.root, { disabled }), rest)}
+      />
+    </SegmentGroupCtx.Provider>
+  )
+})
+
+const KEY_STEP: Record<string, number> = { ArrowRight: 1, ArrowDown: 1, ArrowLeft: -1, ArrowUp: -1 }
+
+export interface SegmentGroupItemProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'value'> {
+  value: string
+}
+
+const Item = forwardRef<HTMLButtonElement, SegmentGroupItemProps>(function SegmentGroupItem(
+  { value: itemValue, disabled: itemDisabled, onClick, onKeyDown, ...rest },
+  ref,
+) {
+  const { value, disabled: groupDisabled, tabStop, selectValue } = useSegmentGroupCtx()
+  const selected = value === itemValue
+  const disabled = groupDisabled || Boolean(itemDisabled)
+
+  return (
+    <button
+      ref={ref}
+      type="button"
+      role="radio"
+      aria-checked={selected}
+      data-value={itemValue}
+      disabled={disabled}
+      tabIndex={itemValue === tabStop ? 0 : -1}
+      {...mergeProps(
+        partOnlyAttrs(segmentGroupAnatomy.item, {
+          state: selected ? 'selected' : 'unselected',
+          disabled,
+        }),
+        {
+          onClick: (e: MouseEvent<HTMLButtonElement>) => {
+            onClick?.(e)
+            if (!e.defaultPrevented) selectValue(itemValue)
+          },
+          onKeyDown: (e: KeyboardEvent<HTMLButtonElement>) => {
+            onKeyDown?.(e)
+            if (e.defaultPrevented) return
+            const root = e.currentTarget.closest<HTMLElement>(ROOT)
+            const items = root ? enabledItems(root) : []
+            const at = items.indexOf(e.currentTarget)
+            const step = KEY_STEP[e.key]
+            const target =
+              e.key === 'Home' ? items[0]
+              : e.key === 'End' ? items[items.length - 1]
+              : step === undefined || at < 0 ? undefined
+              : items[(at + step + items.length) % items.length]
+            if (!target) return
+            e.preventDefault()
+            target.focus()
+            selectValue(target.dataset.value ?? '')
+          },
+        },
+        rest,
+      )}
+    />
+  )
+})
+
+export const SegmentGroup = { Root, Item }

package/packages/react/src/select/index.tsx

@@ -14,8 +14,10 @@ import {
   type KeyboardEvent,
   type MouseEvent,
   type ReactNode,
+  type RefObject,
 } from 'react'
 import { FloatingPositioner } from '../floating/FloatingPositioner.js'
+import type { AnchorPlacement } from '../hooks/use-anchor-position.js'
 import { useAeonMachine } from '../hooks/use-aeon-machine.js'
 import { useOutsideClick } from '../hooks/use-outside-click.js'
 import { mergeProps } from '../utils/merge-props.js'
@@ -257,11 +259,16 @@ const Trigger = forwardRef<HTMLButtonElement, ButtonHTMLAttributes<HTMLButtonEle
 export interface SelectPositionerProps extends HTMLAttributes<HTMLDivElement> {
   /** Mount listbox in document.body (default true). */
   portalled?: boolean
+  placement?: AnchorPlacement
+  /** Align to this region rather than the trigger. See `FloatingPositioner`. */
+  anchorRef?: RefObject<HTMLElement | null>
+  /** Size the listbox to the anchor (default true). */
+  matchAnchorWidth?: boolean
   children?: ReactNode
 }
 
 const Positioner = forwardRef<HTMLDivElement, SelectPositionerProps>(function SelectPositioner(
-  { portalled = true, children, className, ...rest },
+  { portalled = true, placement, anchorRef, matchAnchorWidth = true, children, className, ...rest },
   ref,
 ) {
   const { open, triggerRef, positionerRef } = useSelectCtx()
@@ -275,8 +282,10 @@ const Positioner = forwardRef<HTMLDivElement, SelectPositionerProps>(function Se
         part={selectAnatomy.positioner}
         triggerRef={triggerRef}
         positionerRef={positionerRef}
+        anchorRef={anchorRef}
         portalled={portalled}
-        matchAnchorWidth
+        placement={placement}
+        matchAnchorWidth={matchAnchorWidth}
         className={className}
         {...rest}
       >