aeon-ui-engine 1.0.0

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

@@ -0,0 +1,275 @@
+import { dialogAnatomy, partAttrs } from '@aeon-ui/core'
+import { dialogMachine } from '@aeon-ui/primitives'
+import {
+  createContext,
+  forwardRef,
+  useContext,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  type ButtonHTMLAttributes,
+  type HTMLAttributes,
+  type KeyboardEvent,
+  type MouseEvent,
+  type ReactNode,
+} from 'react'
+import { useAeonMachine } from '../hooks/use-aeon-machine.js'
+import { useFocusTrap } from '../hooks/use-focus-trap.js'
+import { renderPortalled, usePortalledMount } from '../hooks/use-portalled.js'
+import { useScrollLock } from '../hooks/use-scroll-lock.js'
+import { mergeProps } from '../utils/merge-props.js'
+
+interface DialogContextValue {
+  open: boolean
+  send: ReturnType<typeof useAeonMachine<typeof dialogMachine>>[1]
+  titleId: string
+  descriptionId: string
+  contentRef: React.RefObject<HTMLDivElement | null>
+}
+
+const DialogCtx = createContext<DialogContextValue | null>(null)
+
+function useDialogCtx() {
+  const ctx = useContext(DialogCtx)
+  if (!ctx) throw new Error('Dialog parts must be used within Dialog.Root')
+  return ctx
+}
+
+export interface DialogRootProps {
+  open?: boolean
+  defaultOpen?: boolean
+  onOpenChange?: (open: boolean) => void
+  children?: ReactNode
+  className?: string
+}
+
+const Root = forwardRef<HTMLDivElement, DialogRootProps>(function DialogRoot(
+  { open, defaultOpen = false, onOpenChange, children, className, ...rest },
+  ref,
+) {
+  const [snapshot, send] = useAeonMachine(dialogMachine, {
+    input: { open: defaultOpen },
+  })
+
+  const resolvedOpen = open ?? snapshot.context.open
+  const contentRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    onOpenChange?.(resolvedOpen)
+  }, [resolvedOpen, onOpenChange])
+
+  useEffect(() => {
+    if (open !== undefined) {
+      send({ type: 'SET_OPEN', open })
+    }
+  }, [open, send])
+
+  const titleId = useId()
+  const descriptionId = useId()
+  const value = useMemo(
+    () => ({ open: resolvedOpen, send, titleId, descriptionId, contentRef }),
+    [resolvedOpen, send, titleId, descriptionId],
+  )
+
+  return (
+    <DialogCtx.Provider value={value}>
+      <div
+        ref={ref}
+        className={className}
+        {...mergeProps(
+          partAttrs(dialogAnatomy.scope, dialogAnatomy.root, {
+            state: resolvedOpen ? 'open' : 'closed',
+          }),
+          rest as HTMLAttributes<HTMLDivElement>,
+        )}
+      >
+        {children}
+      </div>
+    </DialogCtx.Provider>
+  )
+})
+
+const Trigger = forwardRef<HTMLButtonElement, ButtonHTMLAttributes<HTMLButtonElement>>(function DialogTrigger(
+  { onClick, ...rest },
+  ref,
+) {
+  const { send } = useDialogCtx()
+  return (
+    <button
+      ref={ref}
+      type="button"
+      {...mergeProps(
+        partAttrs(dialogAnatomy.scope, dialogAnatomy.trigger),
+        {
+          onClick: (e: MouseEvent<HTMLButtonElement>) => {
+            onClick?.(e)
+            send({ type: 'OPEN' })
+          },
+        },
+        rest,
+      )}
+    />
+  )
+})
+
+export interface DialogPortalProps extends HTMLAttributes<HTMLDivElement> {
+  /** Mount overlay in document.body (default true). */
+  portalled?: boolean
+  children?: ReactNode
+}
+
+const Portal = forwardRef<HTMLDivElement, DialogPortalProps>(function DialogPortal(
+  { portalled = true, children, className, ...rest },
+  ref,
+) {
+  const { open } = useDialogCtx()
+  const mounted = usePortalledMount()
+
+  useScrollLock(open)
+
+  if (!open) return null
+
+  const node = (
+    <div
+      ref={ref}
+      className={className}
+      {...mergeProps(partAttrs(dialogAnatomy.scope, dialogAnatomy.portal, { state: 'open' }), rest)}
+    >
+      {children}
+    </div>
+  )
+
+  return renderPortalled(node, portalled, mounted)
+})
+
+const Backdrop = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(function DialogBackdrop(
+  props,
+  ref,
+) {
+  const { open, send } = useDialogCtx()
+  if (!open) return null
+  return (
+    <div
+      ref={ref}
+      {...mergeProps(
+        partAttrs(dialogAnatomy.scope, dialogAnatomy.backdrop, { state: 'open' }),
+        {
+          onClick: () => send({ type: 'POINTER_DOWN_OUTSIDE' }),
+        },
+        props,
+      )}
+    />
+  )
+})
+
+const Positioner = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(function DialogPositioner(
+  props,
+  ref,
+) {
+  const { open } = useDialogCtx()
+  if (!open) return null
+  return (
+    <div
+      ref={ref}
+      {...mergeProps(partAttrs(dialogAnatomy.scope, dialogAnatomy.positioner, { state: 'open' }), props)}
+    />
+  )
+})
+
+const Content = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(function DialogContent(
+  { onKeyDown, ...rest },
+  ref,
+) {
+  const { open, send, titleId, descriptionId, contentRef } = useDialogCtx()
+
+  useFocusTrap(contentRef, open)
+
+  useEffect(() => {
+    if (open) contentRef.current?.focus()
+  }, [open, contentRef])
+
+  if (!open) return null
+  return (
+    <div
+      ref={(node) => {
+        contentRef.current = node
+        if (typeof ref === 'function') ref(node)
+        else if (ref) ref.current = node
+      }}
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby={titleId}
+      aria-describedby={descriptionId}
+      tabIndex={-1}
+      {...mergeProps(
+        partAttrs(dialogAnatomy.scope, dialogAnatomy.content, { state: 'open' }),
+        {
+          onKeyDown: (e: KeyboardEvent<HTMLDivElement>) => {
+            onKeyDown?.(e)
+            if (e.key === 'Escape') send({ type: 'ESCAPE' })
+          },
+        },
+        rest,
+      )}
+    />
+  )
+})
+
+const Title = forwardRef<HTMLHeadingElement, HTMLAttributes<HTMLHeadingElement>>(function DialogTitle(
+  props,
+  ref,
+) {
+  const { titleId } = useDialogCtx()
+  return (
+    <h2 ref={ref} id={titleId} {...mergeProps(partAttrs(dialogAnatomy.scope, dialogAnatomy.title), props)} />
+  )
+})
+
+const Description = forwardRef<HTMLParagraphElement, HTMLAttributes<HTMLParagraphElement>>(
+  function DialogDescription(props, ref) {
+    const { descriptionId } = useDialogCtx()
+    return (
+      <p
+        ref={ref}
+        id={descriptionId}
+        {...mergeProps(partAttrs(dialogAnatomy.scope, dialogAnatomy.description), props)}
+      />
+    )
+  },
+)
+
+const CloseTrigger = forwardRef<HTMLButtonElement, ButtonHTMLAttributes<HTMLButtonElement>>(
+  function DialogCloseTrigger({ onClick, ...rest }, ref) {
+    const { send } = useDialogCtx()
+    return (
+      <button
+        ref={ref}
+        type="button"
+        {...mergeProps(
+          partAttrs(dialogAnatomy.scope, dialogAnatomy.closeTrigger),
+          {
+            'aria-label': 'Close dialog',
+            onClick: (e: MouseEvent<HTMLButtonElement>) => {
+              onClick?.(e)
+              send({ type: 'CLOSE' })
+            },
+          },
+          rest,
+        )}
+      />
+    )
+  },
+)
+
+export const Dialog = {
+  Root,
+  Trigger,
+  Portal,
+  Backdrop,
+  Positioner,
+  Content,
+  Title,
+  Description,
+  CloseTrigger,
+}

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

@@ -0,0 +1,172 @@
+import { fieldAnatomy, partAttrs, partOnlyAttrs, stateToAttr } from '@aeon-ui/core'
+import { fieldMachine } from '@aeon-ui/primitives'
+import {
+  createContext,
+  forwardRef,
+  useContext,
+  useMemo,
+  type ChangeEvent,
+  type FocusEvent,
+  type InputHTMLAttributes,
+  type LabelHTMLAttributes,
+  type ReactNode,
+  type TextareaHTMLAttributes,
+} from 'react'
+import { useAeonMachine } from '../hooks/use-aeon-machine.js'
+import { mergeProps } from '../utils/merge-props.js'
+
+interface FieldContextValue {
+  stateAttr: string
+  send: ReturnType<typeof useAeonMachine<typeof fieldMachine>>[1]
+  invalid: boolean
+  pending: boolean
+}
+
+const FieldCtx = createContext<FieldContextValue | null>(null)
+
+export function useFieldContext(): FieldContextValue {
+  const ctx = useContext(FieldCtx)
+  if (!ctx) throw new Error('Field parts must be used within <Field.Root>')
+  return ctx
+}
+
+export interface FieldRootProps {
+  children: ReactNode
+  className?: string
+  id?: string
+}
+
+const Root = forwardRef<HTMLDivElement, FieldRootProps>(function FieldRoot(
+  { children, className, id },
+  ref,
+) {
+  const [snapshot, send] = useAeonMachine(fieldMachine)
+  const stateAttr = stateToAttr(snapshot.value)
+  const invalid =
+    typeof snapshot.value === 'object' &&
+    snapshot.value !== null &&
+    'validation' in snapshot.value &&
+    (snapshot.value as { validation: string }).validation === 'invalid'
+  const pending =
+    typeof snapshot.value === 'object' &&
+    snapshot.value !== null &&
+    'submission' in snapshot.value &&
+    (snapshot.value as { submission: string }).submission === 'pending'
+
+  const value = useMemo(
+    () => ({ stateAttr, send, invalid, pending }),
+    [stateAttr, send, invalid, pending],
+  )
+
+  return (
+    <FieldCtx.Provider value={value}>
+      <div
+        ref={ref}
+        id={id}
+        className={className}
+        {...partAttrs(fieldAnatomy.scope, fieldAnatomy.root, { state: stateAttr })}
+      >
+        {children}
+      </div>
+    </FieldCtx.Provider>
+  )
+})
+
+const Label = forwardRef<HTMLLabelElement, LabelHTMLAttributes<HTMLLabelElement>>(function FieldLabel(
+  props,
+  ref,
+) {
+  return <label ref={ref} {...partOnlyAttrs(fieldAnatomy.label)} {...props} />
+})
+
+export interface FieldControlProps extends InputHTMLAttributes<HTMLInputElement> {
+  validate?: (value: string) => boolean
+}
+
+const Control = forwardRef<HTMLInputElement, FieldControlProps>(function FieldControl(
+  { validate, onChange, onBlur, ...rest },
+  ref,
+) {
+  const { send, invalid } = useFieldContext()
+
+  return (
+    <input
+      ref={ref}
+      aria-invalid={invalid || undefined}
+      {...partOnlyAttrs(fieldAnatomy.control)}
+      {...mergeProps(
+        {
+          onChange: (e: ChangeEvent<HTMLInputElement>) => {
+            send({ type: 'INPUT' })
+            const ok = validate?.(e.target.value) ?? true
+            send({ type: 'VALIDATE', valid: ok })
+            onChange?.(e)
+          },
+          onBlur: (e: FocusEvent<HTMLInputElement>) => {
+            send({ type: 'BLUR' })
+            onBlur?.(e)
+          },
+        },
+        rest,
+      )}
+    />
+  )
+})
+
+export interface FieldTextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
+  validate?: (value: string) => boolean
+}
+
+const Textarea = forwardRef<HTMLTextAreaElement, FieldTextareaProps>(function FieldTextarea(
+  { validate, onChange, onBlur, ...rest },
+  ref,
+) {
+  const { send, invalid } = useFieldContext()
+
+  return (
+    <textarea
+      ref={ref}
+      aria-invalid={invalid || undefined}
+      {...partOnlyAttrs(fieldAnatomy.textarea)}
+      {...mergeProps(
+        {
+          onChange: (e: ChangeEvent<HTMLTextAreaElement>) => {
+            send({ type: 'INPUT' })
+            const ok = validate?.(e.target.value) ?? true
+            send({ type: 'VALIDATE', valid: ok })
+            onChange?.(e)
+          },
+          onBlur: (e: FocusEvent<HTMLTextAreaElement>) => {
+            send({ type: 'BLUR' })
+            onBlur?.(e)
+          },
+        },
+        rest,
+      )}
+    />
+  )
+})
+
+const Message = forwardRef<HTMLParagraphElement, React.HTMLAttributes<HTMLParagraphElement>>(
+  function FieldMessage(props, ref) {
+    const { invalid } = useFieldContext()
+    if (!invalid) return null
+    return (
+      <p
+        ref={ref}
+        role="alert"
+        {...partOnlyAttrs(fieldAnatomy.message, { state: 'invalid' })}
+        {...props}
+      />
+    )
+  },
+)
+
+const Hint = forwardRef<HTMLParagraphElement, React.HTMLAttributes<HTMLParagraphElement>>(
+  function FieldHint(props, ref) {
+    return <p ref={ref} {...partOnlyAttrs(fieldAnatomy.hint)} {...props} />
+  },
+)
+
+export const Field = { Root, Label, Control, Textarea, Message, Hint }
+export { fieldMachine }

package/packages/react/src/hooks/use-aeon-machine.ts

@@ -0,0 +1,10 @@
+import { useMachine } from '@xstate/react'
+import type { AnyStateMachine } from 'xstate'
+
+/** Bridge executable statecharts to React — UI = f(snapshot). */
+export function useAeonMachine<M extends AnyStateMachine>(
+  machine: M,
+  options?: Parameters<typeof useMachine<M>>[1],
+) {
+  return useMachine(machine, options)
+}

package/packages/react/src/hooks/use-anchor-position.ts

@@ -0,0 +1,33 @@
+import { useEffect, type RefObject } from 'react'
+
+/** Pin floating listbox to trigger rect (for portalled selects). */
+export function useAnchorPosition(
+  anchorRef: RefObject<HTMLElement | null>,
+  floatingRef: RefObject<HTMLElement | null>,
+  active: boolean,
+) {
+  useEffect(() => {
+    if (!active || !anchorRef.current || !floatingRef.current) return
+
+    const update = () => {
+      const anchor = anchorRef.current
+      const floating = floatingRef.current
+      if (!anchor || !floating) return
+      const rect = anchor.getBoundingClientRect()
+      floating.style.position = 'fixed'
+      floating.style.top = `${rect.bottom + 4}px`
+      floating.style.left = `${rect.left}px`
+      floating.style.width = `${rect.width}px`
+      floating.style.minWidth = `${rect.width}px`
+      floating.style.zIndex = '50'
+    }
+
+    update()
+    window.addEventListener('resize', update)
+    window.addEventListener('scroll', update, true)
+    return () => {
+      window.removeEventListener('resize', update)
+      window.removeEventListener('scroll', update, true)
+    }
+  }, [active, anchorRef, floatingRef])
+}

package/packages/react/src/hooks/use-focus-trap.ts

@@ -0,0 +1,51 @@
+import { useEffect, type RefObject } from 'react'
+
+const FOCUSABLE =
+  'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])'
+
+function getFocusable(container: HTMLElement): HTMLElement[] {
+  return Array.from(container.querySelectorAll<HTMLElement>(FOCUSABLE)).filter(
+    (el) => !el.hasAttribute('disabled') && el.tabIndex !== -1,
+  )
+}
+
+/** Keep Tab cycles inside `container` while `active`. Restores focus on deactivate. */
+export function useFocusTrap(containerRef: RefObject<HTMLElement | null>, active: boolean) {
+  useEffect(() => {
+    if (!active || !containerRef.current) return
+
+    const container = containerRef.current
+    const previous = document.activeElement
+
+    const focusables = getFocusable(container)
+    focusables[0]?.focus()
+
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key !== 'Tab') return
+      const nodes = getFocusable(container)
+      if (nodes.length === 0) return
+
+      const first = nodes[0]!
+      const last = nodes[nodes.length - 1]!
+      const current = document.activeElement
+
+      if (e.shiftKey) {
+        if (current === first || !container.contains(current)) {
+          e.preventDefault()
+          last.focus()
+        }
+      } else if (current === last || !container.contains(current)) {
+        e.preventDefault()
+        first.focus()
+      }
+    }
+
+    document.addEventListener('keydown', onKeyDown)
+    return () => {
+      document.removeEventListener('keydown', onKeyDown)
+      if (previous instanceof HTMLElement && document.contains(previous)) {
+        previous.focus()
+      }
+    }
+  }, [active, containerRef])
+}

package/packages/react/src/hooks/use-layout-mode.ts

@@ -0,0 +1,22 @@
+import type { LayoutCompositionSpec, LayoutMode, ResponsiveLayoutSpec } from '@aeon-ui/core'
+import { getCompactMq, layoutCompositionForMode, matchLayoutMode } from '@aeon-ui/core'
+import { useEffect, useMemo, useState } from 'react'
+
+export function useLayoutMode(spec: ResponsiveLayoutSpec): {
+  mode: LayoutMode
+  composition: LayoutCompositionSpec
+} {
+  const mq = useMemo(() => getCompactMq(spec), [spec.compactMq])
+  const [mode, setMode] = useState<LayoutMode>(() => matchLayoutMode(spec, mq))
+
+  useEffect(() => {
+    const sync = () => setMode(matchLayoutMode(spec, mq))
+    sync()
+    mq.addEventListener('change', sync)
+    return () => mq.removeEventListener('change', sync)
+  }, [spec, mq])
+
+  const composition = useMemo(() => layoutCompositionForMode(spec, mode), [spec, mode])
+
+  return { mode, composition }
+}

package/packages/react/src/hooks/use-outside-click.ts

@@ -0,0 +1,19 @@
+import { useEffect, type RefObject } from 'react'
+
+/** Close floating content when pointer down occurs outside the container. */
+export function useOutsideClick(
+  refs: RefObject<HTMLElement | null>[],
+  enabled: boolean,
+  onOutside: () => void,
+) {
+  useEffect(() => {
+    if (!enabled) return
+    const onDown = (e: MouseEvent) => {
+      const target = e.target as Node
+      if (refs.some((r) => r.current?.contains(target))) return
+      onOutside()
+    }
+    document.addEventListener('mousedown', onDown)
+    return () => document.removeEventListener('mousedown', onDown)
+  }, [refs, enabled, onOutside])
+}

package/packages/react/src/hooks/use-portalled.ts

@@ -0,0 +1,16 @@
+import { useEffect, useState, type ReactNode } from 'react'
+import { createPortal } from 'react-dom'
+
+/** Client-only gate before `createPortal` (SSR/hydration). */
+export function usePortalledMount() {
+  const [mounted, setMounted] = useState(false)
+  useEffect(() => {
+    setMounted(true)
+  }, [])
+  return mounted
+}
+
+export function renderPortalled(node: ReactNode, portalled: boolean, mounted: boolean) {
+  if (!portalled || !mounted) return node
+  return createPortal(node, document.body)
+}

package/packages/react/src/hooks/use-scroll-lock.ts

@@ -0,0 +1,13 @@
+import { useEffect } from 'react'
+
+/** Prevent body scroll while overlays are open (modal dialogs). */
+export function useScrollLock(active: boolean) {
+  useEffect(() => {
+    if (!active) return
+    const prev = document.body.style.overflow
+    document.body.style.overflow = 'hidden'
+    return () => {
+      document.body.style.overflow = prev
+    }
+  }, [active])
+}

package/packages/react/src/index.ts

@@ -0,0 +1,18 @@
+export * from './button/index.js'
+export * from './switch/index.js'
+export * from './checkbox/index.js'
+export * from './dialog/index.js'
+export * from './tabs/index.js'
+export * from './accordion/index.js'
+export * from './async/index.js'
+export * from './field/index.js'
+export * from './scroll/index.js'
+export * from './select/index.js'
+export * from './combobox/index.js'
+export * from './popover/index.js'
+export * from './menu/index.js'
+export * from './tooltip/index.js'
+export * from './toast/index.js'
+export * from './avatar/index.js'
+export { useAeonMachine } from './hooks/use-aeon-machine.js'
+export { useLayoutMode } from './hooks/use-layout-mode.js'