aeon-ui-engine 1.3.5 → 1.5.1

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

@@ -129,11 +129,15 @@ export interface MenuPositionerProps extends HTMLAttributes<HTMLDivElement> {
   /** Mount menu in document.body (default true). */
   portalled?: boolean
   placement?: AnchorPlacement
+  /** Gap between trigger and menu (default 4). */
+  gutter?: number
+  /** Stack level for the portalled surface (default 50). */
+  zIndex?: number
   children?: ReactNode
 }
 
 const Positioner = forwardRef<HTMLDivElement, MenuPositionerProps>(function MenuPositioner(
-  { portalled = true, placement = 'bottom-start', children, className, ...rest },
+  { portalled = true, placement = 'bottom-start', gutter, zIndex, children, className, ...rest },
   ref,
 ) {
   const { open, triggerRef, positionerRef } = useMenuCtx()
@@ -148,6 +152,8 @@ const Positioner = forwardRef<HTMLDivElement, MenuPositionerProps>(function Menu
       positionerRef={positionerRef}
       portalled={portalled}
       placement={placement}
+      gutter={gutter}
+      zIndex={zIndex}
       className={className}
       {...rest}
     >
@@ -160,13 +166,41 @@ const Content = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(funct
   { onKeyDown, ...rest },
   ref,
 ) {
-  const { open, send, menuId } = useMenuCtx()
+  const { open, send, menuId, triggerRef } = useMenuCtx()
+  const contentRef = useRef<HTMLDivElement | null>(null)
+
+  // Focus enters the surface while it is open and returns to the trigger on
+  // dismiss, so keyboard users stay inside the menu they opened.
+  useEffect(() => {
+    if (!open) return
+    const trigger = triggerRef.current
+    contentRef.current?.focus({ preventScroll: true })
+    return () => {
+      if (trigger?.isConnected) trigger.focus({ preventScroll: true })
+    }
+  }, [open, triggerRef])
+
+  // Escape closes wherever focus sits — trigger, item or elsewhere on the page.
+  useEffect(() => {
+    if (!open) return
+    const onDocumentKeyDown = (event: globalThis.KeyboardEvent) => {
+      if (event.key === 'Escape') send({ type: 'ESCAPE' })
+    }
+    document.addEventListener('keydown', onDocumentKeyDown)
+    return () => document.removeEventListener('keydown', onDocumentKeyDown)
+  }, [open, send])
+
   if (!open) return null
   return (
     <div
-      ref={ref}
+      ref={(node) => {
+        contentRef.current = node
+        if (typeof ref === 'function') ref(node)
+        else if (ref) ref.current = node
+      }}
       id={menuId}
       role="menu"
+      tabIndex={-1}
       {...mergeProps(
         partAttrs(menuAnatomy.scope, menuAnatomy.content, { state: 'open' }),
         {

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

@@ -132,11 +132,15 @@ export interface PopoverPositionerProps extends HTMLAttributes<HTMLDivElement> {
   /** Mount panel in document.body (default true). */
   portalled?: boolean
   placement?: AnchorPlacement
+  /** Gap between trigger and panel (default 4). */
+  gutter?: number
+  /** Stack level for the portalled surface (default 50). */
+  zIndex?: number
   children?: ReactNode
 }
 
 const Positioner = forwardRef<HTMLDivElement, PopoverPositionerProps>(function PopoverPositioner(
-  { portalled = true, placement = 'bottom-start', children, className, ...rest },
+  { portalled = true, placement = 'bottom-start', gutter, zIndex, children, className, ...rest },
   ref,
 ) {
   const { open, triggerRef, positionerRef } = usePopoverCtx()
@@ -151,6 +155,8 @@ const Positioner = forwardRef<HTMLDivElement, PopoverPositionerProps>(function P
       positionerRef={positionerRef}
       portalled={portalled}
       placement={placement}
+      gutter={gutter}
+      zIndex={zIndex}
       className={className}
       {...rest}
     >

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

@@ -97,6 +97,48 @@ const Amount = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(functi
   )
 })
 
+/** Command verb face — e.g. `/pay` (BRC-218 §4 confirmation). */
+const Verb = forwardRef<HTMLParagraphElement, HTMLAttributes<HTMLParagraphElement>>(
+  function PromptVerb(props, ref) {
+    const { status } = usePromptCtx()
+    return (
+      <p
+        ref={ref}
+        {...mergeProps(partAttrs(promptAnatomy.scope, promptAnatomy.verb, { state: status }), props)}
+      />
+    )
+  },
+)
+
+/** Fully-qualified recipient `@handle@domain` — never alias alone. */
+const Recipient = forwardRef<HTMLParagraphElement, HTMLAttributes<HTMLParagraphElement>>(
+  function PromptRecipient(props, ref) {
+    const { status } = usePromptCtx()
+    return (
+      <p
+        ref={ref}
+        {...mergeProps(
+          partAttrs(promptAnatomy.scope, promptAnatomy.recipient, { state: status }),
+          props,
+        )}
+      />
+    )
+  },
+)
+
+/** Plain-language effect statement for the confirmation sheet. */
+const Effect = forwardRef<HTMLParagraphElement, HTMLAttributes<HTMLParagraphElement>>(
+  function PromptEffect(props, ref) {
+    const { status } = usePromptCtx()
+    return (
+      <p
+        ref={ref}
+        {...mergeProps(partAttrs(promptAnatomy.scope, promptAnatomy.effect, { state: status }), props)}
+      />
+    )
+  },
+)
+
 const Actions = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(function PromptActions(
   props,
   ref,
@@ -155,6 +197,9 @@ export const Prompt = {
   Eyebrow,
   Meta,
   Amount,
+  Verb,
+  Recipient,
+  Effect,
   Actions,
   Primary,
   Secondary,

package/packages/react/src/range-slider/index.tsx

@@ -0,0 +1,322 @@
+import { partAttrs, partOnlyAttrs, rangeSliderAnatomy } from '@aeon-ui/core'
+import {
+  rangeSliderMachine,
+  snapRangeSliderValue,
+} from '@aeon-ui/primitives'
+import {
+  createContext,
+  forwardRef,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  type HTMLAttributes,
+  type KeyboardEvent,
+  type PointerEvent,
+  type ReactNode,
+} from 'react'
+import { useAeonMachine } from '../hooks/use-aeon-machine.js'
+import { mergeProps } from '../utils/merge-props.js'
+
+type ThumbIndex = 0 | 1
+
+interface RangeSliderContextValue {
+  values: [number, number]
+  min: number
+  max: number
+  step: number
+  disabled: boolean
+  dragging: boolean
+  activeThumb: ThumbIndex | null
+  send: ReturnType<typeof useAeonMachine<typeof rangeSliderMachine>>[1]
+  setThumbFromClientX: (thumb: ThumbIndex, clientX: number) => void
+  trackRef: React.RefObject<HTMLDivElement | null>
+}
+
+const RangeSliderCtx = createContext<RangeSliderContextValue | null>(null)
+
+function useRangeSliderCtx() {
+  const ctx = useContext(RangeSliderCtx)
+  if (!ctx) throw new Error('RangeSlider parts must be used within RangeSlider.Root')
+  return ctx
+}
+
+function percent(value: number, min: number, max: number) {
+  if (max <= min) return 0
+  return ((value - min) / (max - min)) * 100
+}
+
+export interface RangeSliderRootProps {
+  value?: [number, number]
+  defaultValue?: [number, number]
+  min?: number
+  max?: number
+  step?: number
+  minStepsBetween?: number
+  disabled?: boolean
+  onValueChange?: (value: [number, number]) => void
+  children?: ReactNode
+  className?: string
+}
+
+const Root = forwardRef<HTMLDivElement, RangeSliderRootProps>(function RangeSliderRoot(
+  {
+    value,
+    defaultValue,
+    min = 0,
+    max = 100,
+    step = 1,
+    minStepsBetween = 0,
+    disabled = false,
+    onValueChange,
+    children,
+    className,
+    ...rest
+  },
+  ref,
+) {
+  const trackRef = useRef<HTMLDivElement>(null)
+  const [snapshot, send] = useAeonMachine(rangeSliderMachine, {
+    input: {
+      values: defaultValue ?? [min, max],
+      min,
+      max,
+      step,
+      minStepsBetween,
+      disabled,
+    },
+  })
+
+  const resolvedValues = value ?? snapshot.context.values
+  const dragging = snapshot.matches({ interaction: 'dragging' })
+  const activeThumb = snapshot.context.activeThumb
+
+  useEffect(() => {
+    if (value !== undefined) send({ type: 'SET_VALUES', values: value })
+  }, [value, send])
+
+  useEffect(() => {
+    send({ type: 'SET_BOUNDS', min, max, step, minStepsBetween })
+  }, [min, max, step, minStepsBetween, send])
+
+  useEffect(() => {
+    send({ type: 'SET_DISABLED', disabled })
+  }, [disabled, send])
+
+  const setThumbFromClientX = useCallback(
+    (thumb: ThumbIndex, clientX: number) => {
+      const track = trackRef.current
+      if (!track || disabled) return
+      const rect = track.getBoundingClientRect()
+      if (rect.width <= 0) return
+      const ratio = Math.min(1, Math.max(0, (clientX - rect.left) / rect.width))
+      const next = snapRangeSliderValue(min + ratio * (max - min), min, max, step)
+      send({ type: 'POINTER_MOVE', value: next })
+      if (value === undefined) {
+        // Machine updates async via snapshot; notify after POINTER_MOVE by reading next tick
+        // Consumers in uncontrolled mode get onValueChange from effect below.
+      }
+      void thumb
+    },
+    [disabled, min, max, step, send, value],
+  )
+
+  const lastNotified = useRef<string>('')
+  useEffect(() => {
+    const key = resolvedValues.join(',')
+    if (key === lastNotified.current) return
+    lastNotified.current = key
+    onValueChange?.(resolvedValues)
+  }, [resolvedValues, onValueChange])
+
+  useEffect(() => {
+    if (!dragging) return
+    const onMove = (e: globalThis.PointerEvent) => {
+      if (activeThumb == null) return
+      setThumbFromClientX(activeThumb, e.clientX)
+    }
+    const onUp = () => send({ type: 'POINTER_UP' })
+    window.addEventListener('pointermove', onMove)
+    window.addEventListener('pointerup', onUp)
+    return () => {
+      window.removeEventListener('pointermove', onMove)
+      window.removeEventListener('pointerup', onUp)
+    }
+  }, [dragging, activeThumb, setThumbFromClientX, send])
+
+  const ctx = useMemo(
+    () => ({
+      values: resolvedValues,
+      min,
+      max,
+      step,
+      disabled,
+      dragging,
+      activeThumb,
+      send,
+      setThumbFromClientX,
+      trackRef,
+    }),
+    [
+      resolvedValues,
+      min,
+      max,
+      step,
+      disabled,
+      dragging,
+      activeThumb,
+      send,
+      setThumbFromClientX,
+    ],
+  )
+
+  return (
+    <RangeSliderCtx.Provider value={ctx}>
+      <div
+        ref={ref}
+        className={className}
+        {...mergeProps(
+          partAttrs(rangeSliderAnatomy.scope, rangeSliderAnatomy.root, {
+            state: dragging ? 'dragging' : 'idle',
+            disabled,
+          }),
+          rest as HTMLAttributes<HTMLDivElement>,
+        )}
+      >
+        {children}
+      </div>
+    </RangeSliderCtx.Provider>
+  )
+})
+
+const Track = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(function RangeSliderTrack(
+  { onPointerDown, ...rest },
+  ref,
+) {
+  const { disabled, values, send, setThumbFromClientX, trackRef, min, max } = useRangeSliderCtx()
+
+  return (
+    <div
+      ref={(node) => {
+        trackRef.current = node
+        if (typeof ref === 'function') ref(node)
+        else if (ref) ref.current = node
+      }}
+      {...mergeProps(
+        partOnlyAttrs(rangeSliderAnatomy.track),
+        {
+          onPointerDown: (e: PointerEvent<HTMLDivElement>) => {
+            onPointerDown?.(e)
+            if (disabled || e.button !== 0) return
+            e.currentTarget.setPointerCapture(e.pointerId)
+            const rect = e.currentTarget.getBoundingClientRect()
+            const ratio = Math.min(1, Math.max(0, (e.clientX - rect.left) / rect.width))
+            const pointerValue = min + ratio * (max - min)
+            const dist0 = Math.abs(pointerValue - values[0])
+            const dist1 = Math.abs(pointerValue - values[1])
+            const thumb: ThumbIndex = dist0 <= dist1 ? 0 : 1
+            send({ type: 'POINTER_DOWN', thumb })
+            setThumbFromClientX(thumb, e.clientX)
+          },
+        },
+        rest,
+      )}
+    />
+  )
+})
+
+const Range = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(function RangeSliderRange(
+  { style, ...rest },
+  ref,
+) {
+  const { values, min, max } = useRangeSliderCtx()
+  const left = percent(values[0], min, max)
+  const right = percent(values[1], min, max)
+  return (
+    <div
+      ref={ref}
+      aria-hidden
+      {...mergeProps(partOnlyAttrs(rangeSliderAnatomy.range), rest, {
+        style: { ...style, left: `${left}%`, width: `${Math.max(0, right - left)}%` },
+      })}
+    />
+  )
+})
+
+export interface RangeSliderThumbProps extends HTMLAttributes<HTMLSpanElement> {
+  index: ThumbIndex
+}
+
+const Thumb = forwardRef<HTMLSpanElement, RangeSliderThumbProps>(function RangeSliderThumb(
+  { index, onKeyDown, onPointerDown, style, ...rest },
+  ref,
+) {
+  const { values, min, max, step, disabled, dragging, activeThumb, send, setThumbFromClientX } =
+    useRangeSliderCtx()
+  const value = values[index]
+  const isActive = dragging && activeThumb === index
+
+  return (
+    <span
+      ref={ref}
+      role="slider"
+      tabIndex={disabled ? -1 : 0}
+      aria-valuemin={min}
+      aria-valuemax={max}
+      aria-valuenow={value}
+      aria-disabled={disabled || undefined}
+      data-aeon-index={index}
+      {...mergeProps(
+        partOnlyAttrs(rangeSliderAnatomy.thumb, {
+          state: isActive ? 'dragging' : disabled ? 'disabled' : 'idle',
+        }),
+        {
+          style: { ...style, left: `${percent(value, min, max)}%` },
+          onPointerDown: (e: PointerEvent<HTMLSpanElement>) => {
+            onPointerDown?.(e)
+            if (disabled || e.button !== 0) return
+            e.stopPropagation()
+            e.currentTarget.setPointerCapture(e.pointerId)
+            send({ type: 'POINTER_DOWN', thumb: index })
+            setThumbFromClientX(index, e.clientX)
+          },
+          onKeyDown: (e: KeyboardEvent<HTMLSpanElement>) => {
+            onKeyDown?.(e)
+            if (disabled || e.defaultPrevented) return
+            if (e.key === 'ArrowRight' || e.key === 'ArrowUp') {
+              e.preventDefault()
+              send({ type: 'STEP', thumb: index, delta: step })
+            }
+            if (e.key === 'ArrowLeft' || e.key === 'ArrowDown') {
+              e.preventDefault()
+              send({ type: 'STEP', thumb: index, delta: -step })
+            }
+            if (e.key === 'Home') {
+              e.preventDefault()
+              send({ type: 'HOME', thumb: index })
+            }
+            if (e.key === 'End') {
+              e.preventDefault()
+              send({ type: 'END', thumb: index })
+            }
+          },
+        },
+        rest,
+      )}
+    />
+  )
+})
+
+const ValueText = forwardRef<HTMLSpanElement, HTMLAttributes<HTMLSpanElement>>(
+  function RangeSliderValueText(props, ref) {
+    const { values } = useRangeSliderCtx()
+    return (
+      <span ref={ref} {...mergeProps(partOnlyAttrs(rangeSliderAnatomy.valueText), props)}>
+        {props.children ?? `${values[0]} – ${values[1]}`}
+      </span>
+    )
+  },
+)
+
+export const RangeSlider = { Root, Track, Range, Thumb, ValueText }

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

@@ -25,6 +25,8 @@ interface SliderContextValue {
   dragging: boolean
   send: ReturnType<typeof useAeonMachine<typeof sliderMachine>>[1]
   onValueChange?: (value: number) => void
+  /** Snap, store and report a user-intended value. */
+  commit: (value: number) => void
   setValueFromClientX: (clientX: number) => void
   trackRef: React.RefObject<HTMLDivElement | null>
 }
@@ -83,14 +85,33 @@ const Root = forwardRef<HTMLDivElement, SliderRootProps>(function SliderRoot(
   const resolvedValue = value ?? snapshot.context.value
   const dragging = snapshot.matches({ interaction: 'dragging' })
 
-  useEffect(() => {
-    onValueChange?.(resolvedValue)
-  }, [resolvedValue, onValueChange])
-
   useEffect(() => {
     if (value !== undefined) send({ type: 'SET_VALUE', value })
   }, [value, send])
 
+  useEffect(() => {
+    send({ type: 'SET_BOUNDS', min, max, step })
+  }, [min, max, step, send])
+
+  useEffect(() => {
+    send({ type: 'SET_DISABLED', disabled })
+  }, [disabled, send])
+
+  /**
+   * Interaction is emitted here, never echoed from the resolved value. A
+   * controlled slider therefore reports what the user did (Aeon ≤1.4.0 stayed
+   * silent while `value` was set) and never fires on mount.
+   */
+  const commit = useCallback(
+    (next: number) => {
+      if (disabled) return
+      const snapped = snapSliderValue(next, min, max, step)
+      send({ type: 'SET_VALUE', value: snapped })
+      onValueChange?.(snapped)
+    },
+    [disabled, min, max, step, send, onValueChange],
+  )
+
   const setValueFromClientX = useCallback(
     (clientX: number) => {
       const track = trackRef.current
@@ -98,11 +119,9 @@ const Root = forwardRef<HTMLDivElement, SliderRootProps>(function SliderRoot(
       const rect = track.getBoundingClientRect()
       if (rect.width <= 0) return
       const ratio = Math.min(1, Math.max(0, (clientX - rect.left) / rect.width))
-      const next = snapSliderValue(min + ratio * (max - min), min, max, step)
-      send({ type: 'SET_VALUE', value: next })
-      if (value === undefined) onValueChange?.(next)
+      commit(min + ratio * (max - min))
     },
-    [disabled, min, max, step, send, value, onValueChange],
+    [commit, disabled, min, max],
   )
 
   useEffect(() => {
@@ -127,10 +146,22 @@ const Root = forwardRef<HTMLDivElement, SliderRootProps>(function SliderRoot(
       dragging,
       send,
       onValueChange,
+      commit,
       setValueFromClientX,
       trackRef,
     }),
-    [resolvedValue, min, max, step, disabled, dragging, send, onValueChange, setValueFromClientX],
+    [
+      resolvedValue,
+      min,
+      max,
+      step,
+      disabled,
+      dragging,
+      send,
+      onValueChange,
+      commit,
+      setValueFromClientX,
+    ],
   )
 
   return (
@@ -201,7 +232,8 @@ const Thumb = forwardRef<HTMLSpanElement, HTMLAttributes<HTMLSpanElement>>(funct
   { onKeyDown, onPointerDown, style, ...rest },
   ref,
 ) {
-  const { value, min, max, step, disabled, dragging, send, setValueFromClientX } = useSliderCtx()
+  const { value, min, max, step, disabled, dragging, send, commit, setValueFromClientX } =
+    useSliderCtx()
 
   return (
     <span
@@ -229,19 +261,27 @@ const Thumb = forwardRef<HTMLSpanElement, HTMLAttributes<HTMLSpanElement>>(funct
             if (disabled || e.defaultPrevented) return
             if (e.key === 'ArrowRight' || e.key === 'ArrowUp') {
               e.preventDefault()
-              send({ type: 'STEP', delta: step })
+              commit(value + step)
             }
             if (e.key === 'ArrowLeft' || e.key === 'ArrowDown') {
               e.preventDefault()
-              send({ type: 'STEP', delta: -step })
+              commit(value - step)
+            }
+            if (e.key === 'PageUp') {
+              e.preventDefault()
+              commit(value + (max - min) / 10)
+            }
+            if (e.key === 'PageDown') {
+              e.preventDefault()
+              commit(value - (max - min) / 10)
             }
             if (e.key === 'Home') {
               e.preventDefault()
-              send({ type: 'HOME' })
+              commit(min)
             }
             if (e.key === 'End') {
               e.preventDefault()
-              send({ type: 'END' })
+              commit(max)
             }
           },
         },