aeon-ui-engine 1.0.0

package/packages/primitives/src/machines/toggle.ts

@@ -0,0 +1,61 @@
+import { assign, setup } from 'xstate'
+
+export interface ToggleContext {
+  checked: boolean
+  disabled: boolean
+}
+
+export type ToggleEvent =
+  | { type: 'TOGGLE' }
+  | { type: 'SET_CHECKED'; checked: boolean }
+  | { type: 'POINTER_DOWN' }
+  | { type: 'POINTER_UP' }
+  | { type: 'POINTER_LEAVE' }
+
+/** Checked and unchecked are distinct, stable states. */
+export const toggleMachine = setup({
+  types: {
+    context: {} as ToggleContext,
+    events: {} as ToggleEvent,
+    input: {} as ToggleContext,
+  },
+  guards: {
+    notDisabled: ({ context }) => !context.disabled,
+  },
+  actions: {
+    flip: assign({
+      checked: ({ context }) => !context.checked,
+    }),
+    setChecked: assign({
+      checked: ({ event }) => (event.type === 'SET_CHECKED' ? event.checked : false),
+    }),
+  },
+}).createMachine({
+  id: 'toggle',
+  context: ({ input }) => ({
+    checked: input.checked ?? false,
+    disabled: input.disabled ?? false,
+  }),
+  initial: 'interaction',
+  states: {
+    interaction: {
+      initial: 'idle',
+      states: {
+        idle: {
+          on: {
+            POINTER_DOWN: { target: 'pressed', guard: 'notDisabled' },
+            TOGGLE: { actions: 'flip', guard: 'notDisabled' },
+            SET_CHECKED: { actions: 'setChecked' },
+          },
+        },
+        pressed: {
+          on: {
+            /* Flip on TOGGLE (click/keyboard) only — pointer up is visual press state. */
+            POINTER_UP: 'idle',
+            POINTER_LEAVE: 'idle',
+          },
+        },
+      },
+    },
+  },
+})

package/packages/primitives/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}

package/packages/primitives/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['src/**/*.test.ts', 'src/__tests__/**/*.test.ts'],
+  },
+})

package/packages/react/README.md

@@ -0,0 +1,65 @@
+# @aeon-ui/react
+
+**Headless compound components** — snapshot/props → DOM + accessibility.
+
+Agents: [docs/MACHINES.md](../../docs/MACHINES.md) before editing state wiring.
+
+## Install
+
+```bash
+pnpm add @aeon-ui/react @aeon-ui/core @aeon-ui/primitives
+```
+
+Style yourself with `[data-aeon-*]` or use `@aeon-ui/ui`.
+
+## Usage
+
+```tsx
+import { Dialog, Button, useAeonMachine } from '@aeon-ui/react'
+import { buttonLifecycleMachine } from '@aeon-ui/primitives'
+
+<Dialog.Root>
+  <Dialog.Trigger>Open</Dialog.Trigger>
+  <Dialog.Backdrop />
+  <Dialog.Positioner>
+    <Dialog.Content>
+      <Dialog.Title>Title</Dialog.Title>
+      <Dialog.CloseTrigger>Close</Dialog.CloseTrigger>
+    </Dialog.Content>
+  </Dialog.Positioner>
+</Dialog.Root>
+
+<Button.Root status="pending">Save</Button.Root>
+```
+
+## Catalog
+
+`Button`, `Switch`, `Checkbox`, `Dialog`, `Tabs`, `Accordion`, `Select`, `Combobox`, `Async`, `Field`, `Scroll`, `Menu`, `Popover`, `Tooltip`, `Toast`, `useAeonMachine`, `useLayoutMode`.
+
+See [COMPONENTS.md](../../COMPONENTS.md).
+
+## Patterns
+
+| Pattern | Components |
+|---------|------------|
+| `useAeonMachine` + primitives | Dialog, Switch, Async, Field, Tabs, … |
+| `status` prop | Button |
+| `useState` | Select, Combobox, Tooltip |
+| `getScrollSnapshot` | Scroll |
+
+## Custom wrapper
+
+```tsx
+import { partAttrs, dialogAnatomy } from '@aeon-ui/core'
+
+<button {...partAttrs(dialogAnatomy.scope, dialogAnatomy.trigger, { state: 'closed' })} />
+```
+
+## File layout
+
+`src/<component>/index.tsx` — see [docs/FILE_MAP.md](../../docs/FILE_MAP.md).
+
+## Related
+
+- [INTEGRATION.md](../../INTEGRATION.md)
+- [FRAMEWORKS.md](../../FRAMEWORKS.md)

package/packages/react/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@aeon-ui/react",
+  "version": "0.1.0",
+  "description": "Headless React components backed by XState machines",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GenericCPU/aeon-ui.git",
+    "directory": "packages/react"
+  },
+  "publishConfig": { "access": "public" },
+  "files": ["dist", "README.md"],
+  "keywords": ["aeon-ui", "react", "headless", "xstate", "statechart"],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean --external react --external react-dom",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@aeon-ui/core": "workspace:*",
+    "@aeon-ui/primitives": "workspace:*",
+    "@xstate/react": "^5.0.3",
+    "xstate": "^5.19.2"
+  },
+  "peerDependencies": {
+    "react": "^18 || ^19",
+    "react-dom": "^18 || ^19"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.0",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^19.1.2",
+    "@types/react-dom": "^19.1.2",
+    "jsdom": "^26.1.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  }
+}

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

@@ -0,0 +1,179 @@
+import { accordionAnatomy, partOnlyAttrs, scopeAttrs } from '@aeon-ui/core'
+import { accordionMachine } from '@aeon-ui/primitives'
+import {
+  createContext,
+  forwardRef,
+  useContext,
+  useEffect,
+  useMemo,
+  type ButtonHTMLAttributes,
+  type HTMLAttributes,
+  type MouseEvent,
+  type ReactNode,
+} from 'react'
+import { useAeonMachine } from '../hooks/use-aeon-machine.js'
+import { mergeProps } from '../utils/merge-props.js'
+
+interface AccordionContextValue {
+  value: string[]
+  send: ReturnType<typeof useAeonMachine<typeof accordionMachine>>[1]
+}
+
+const AccordionCtx = createContext<AccordionContextValue | null>(null)
+
+function useAccordionCtx() {
+  const ctx = useContext(AccordionCtx)
+  if (!ctx) throw new Error('Accordion parts must be used within Accordion.Root')
+  return ctx
+}
+
+export interface AccordionRootProps {
+  value?: string[]
+  defaultValue?: string[]
+  multiple?: boolean
+  collapsible?: boolean
+  onValueChange?: (value: string[]) => void
+  children?: ReactNode
+  className?: string
+}
+
+const Root = forwardRef<HTMLDivElement, AccordionRootProps>(function AccordionRoot(
+  {
+    value,
+    defaultValue = [],
+    multiple = false,
+    collapsible = true,
+    onValueChange,
+    children,
+    className,
+    ...rest
+  },
+  ref,
+) {
+  const [snapshot, send] = useAeonMachine(accordionMachine, {
+    input: { value: defaultValue, multiple, collapsible },
+  })
+
+  const resolvedValue = value ?? snapshot.context.value
+
+  useEffect(() => {
+    onValueChange?.(resolvedValue)
+  }, [resolvedValue, onValueChange])
+
+  useEffect(() => {
+    if (value !== undefined) send({ type: 'SET_VALUE', value })
+  }, [value, send])
+
+  const ctx = useMemo(() => ({ value: resolvedValue, send }), [resolvedValue, send])
+
+  return (
+    <AccordionCtx.Provider value={ctx}>
+      <div
+        ref={ref}
+        className={className}
+        {...mergeProps(
+          scopeAttrs(accordionAnatomy.scope, accordionAnatomy.root),
+          rest as HTMLAttributes<HTMLDivElement>,
+        )}
+      >
+        {children}
+      </div>
+    </AccordionCtx.Provider>
+  )
+})
+
+export interface AccordionItemProps extends HTMLAttributes<HTMLDivElement> {
+  value: string
+}
+
+const Item = forwardRef<HTMLDivElement, AccordionItemProps>(function AccordionItem(
+  { value: itemValue, children, ...rest },
+  ref,
+) {
+  const { value } = useAccordionCtx()
+  const open = value.includes(itemValue)
+
+  return (
+    <div
+      ref={ref}
+      {...mergeProps(
+        partOnlyAttrs(accordionAnatomy.item, {
+          state: open ? 'open' : 'closed',
+        }),
+        rest,
+      )}
+    >
+      {children}
+    </div>
+  )
+})
+
+export interface AccordionItemTriggerProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  value: string
+}
+
+const ItemTrigger = forwardRef<HTMLButtonElement, AccordionItemTriggerProps>(function AccordionItemTrigger(
+  { value: itemValue, onClick, ...rest },
+  ref,
+) {
+  const { value, send } = useAccordionCtx()
+  const open = value.includes(itemValue)
+
+  return (
+    <button
+      ref={ref}
+      type="button"
+      aria-expanded={open}
+      {...mergeProps(
+        partOnlyAttrs(accordionAnatomy.itemTrigger, {
+          state: open ? 'open' : 'closed',
+        }),
+        {
+          onClick: (e: MouseEvent<HTMLButtonElement>) => {
+            onClick?.(e)
+            send({ type: 'TOGGLE', item: itemValue })
+          },
+        },
+        rest,
+      )}
+    />
+  )
+})
+
+export interface AccordionItemContentProps extends HTMLAttributes<HTMLDivElement> {
+  value: string
+}
+
+const ItemContent = forwardRef<HTMLDivElement, AccordionItemContentProps>(function AccordionItemContent(
+  { value: itemValue, children, ...rest },
+  ref,
+) {
+  const { value } = useAccordionCtx()
+  if (!value.includes(itemValue)) return null
+
+  return (
+    <div
+      ref={ref}
+      {...mergeProps(
+        partOnlyAttrs(accordionAnatomy.itemContent, { state: 'open' }),
+        rest,
+      )}
+    >
+      {children}
+    </div>
+  )
+})
+
+const ItemIndicator = forwardRef<HTMLSpanElement, HTMLAttributes<HTMLSpanElement>>(function AccordionItemIndicator(
+  props,
+  ref,
+) {
+  return (
+    <span
+      ref={ref}
+      {...mergeProps(partOnlyAttrs(accordionAnatomy.itemIndicator), props)}
+    />
+  )
+})
+
+export const Accordion = { Root, Item, ItemTrigger, ItemContent, ItemIndicator }

package/packages/react/src/async/actions.tsx

@@ -0,0 +1,22 @@
+import { asyncAnatomy, partOnlyAttrs } from '@aeon-ui/core'
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react'
+import { mergeProps } from '../utils/merge-props.js'
+
+export interface AsyncActionsProps extends HTMLAttributes<HTMLDivElement> {
+  children: ReactNode
+}
+
+export const AsyncActions = forwardRef<HTMLDivElement, AsyncActionsProps>(function AsyncActions(
+  { children, className, ...rest },
+  ref,
+) {
+  return (
+    <div
+      ref={ref}
+      className={className}
+      {...mergeProps(partOnlyAttrs(asyncAnatomy.actions), rest)}
+    >
+      {children}
+    </div>
+  )
+})

package/packages/react/src/async/context.tsx

@@ -0,0 +1,54 @@
+import type { AsyncContext } from '@aeon-ui/primitives'
+import { createAsyncMachine } from '@aeon-ui/primitives'
+import { createContext, useContext, useMemo, type ReactNode } from 'react'
+import { useAeonMachine } from '../hooks/use-aeon-machine.js'
+
+const defaultMachine = createAsyncMachine()
+
+export interface AsyncProviderValue {
+  status: string
+  data: unknown
+  error: string | null
+  stale: boolean
+  stateAttr: string
+  send: ReturnType<typeof useAeonMachine<typeof defaultMachine>>[1]
+}
+
+const AsyncCtx = createContext<AsyncProviderValue | null>(null)
+
+export function useAsyncContext(): AsyncProviderValue {
+  const ctx = useContext(AsyncCtx)
+  if (!ctx) {
+    throw new Error('Async compound components must be used within <Async.Root>')
+  }
+  return ctx
+}
+
+export interface AsyncProviderProps {
+  children: ReactNode
+  machine?: typeof defaultMachine
+}
+
+export function AsyncProvider({ children, machine }: AsyncProviderProps) {
+  const resolvedMachine = machine ?? defaultMachine
+  const [snapshot, send] = useAeonMachine(resolvedMachine)
+  const status = String(snapshot.value)
+  const { data, error, stale } = snapshot.context as AsyncContext
+  const stateAttr = stale && status === 'success' ? `${status} stale` : status
+
+  const value = useMemo<AsyncProviderValue>(
+    () => ({
+      send,
+      status,
+      data,
+      error,
+      stale: Boolean(stale),
+      stateAttr,
+    }),
+    [send, status, data, error, stale, stateAttr],
+  )
+
+  return <AsyncCtx.Provider value={value}>{children}</AsyncCtx.Provider>
+}
+
+export type { AsyncEvent } from '@aeon-ui/primitives'

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

@@ -0,0 +1,21 @@
+import { AsyncActions } from './actions.js'
+import { AsyncProvider } from './context.js'
+import { AsyncReadout } from './readout.js'
+import { AsyncRoot } from './root.js'
+import { AsyncTrack } from './track.js'
+
+export { AsyncProvider, useAsyncContext } from './context.js'
+export { AsyncTrack } from './track.js'
+export { AsyncReadout } from './readout.js'
+export { AsyncActions } from './actions.js'
+export { AsyncRoot } from './root.js'
+export { AsyncRegion } from './legacy-region.js'
+export { createAsyncMachine } from '@aeon-ui/primitives'
+
+export const Async = {
+  Root: AsyncRoot,
+  Provider: AsyncProvider,
+  Track: AsyncTrack,
+  Readout: AsyncReadout,
+  Actions: AsyncActions,
+}

package/packages/react/src/async/legacy-region.tsx

@@ -0,0 +1,38 @@
+import { partAttrs } from '@aeon-ui/core'
+import { createAsyncMachine } from '@aeon-ui/primitives'
+import { useMemo, type ReactNode } from 'react'
+import { useAeonMachine } from '../hooks/use-aeon-machine.js'
+import { mergeProps } from '../utils/merge-props.js'
+
+export interface AsyncRegionProps<T = unknown> {
+  children?: ReactNode | ((state: { status: string; data: T | null; error: string | null }) => ReactNode)
+  className?: string
+}
+
+/** @deprecated Prefer `<Async.Root>` with Track, Readout, and Actions. */
+export function AsyncRegion<T = unknown>({ children, className }: AsyncRegionProps<T>) {
+  const machine = useMemo(() => createAsyncMachine<T>(), [])
+  const [snapshot] = useAeonMachine(machine)
+  const status = snapshot.value as string
+  const { data, error } = snapshot.context
+
+  const content =
+    typeof children === 'function' ? children({ status, data: data as T | null, error }) : children
+
+  return (
+    <div
+      className={className}
+      {...mergeProps(partAttrs('async', 'root', { state: status }))}
+    >
+      {content ?? (
+        <>
+          {status === 'idle' && <span data-aeon-part="idle">Ready</span>}
+          {status === 'loading' && <span data-aeon-part="loading">Loading…</span>}
+          {status === 'success' && <span data-aeon-part="success">{String(data)}</span>}
+          {status === 'failure' && <span data-aeon-part="failure">{error}</span>}
+          {status === 'empty' && <span data-aeon-part="empty">No results</span>}
+        </>
+      )}
+    </div>
+  )
+}

package/packages/react/src/async/readout.tsx

@@ -0,0 +1,34 @@
+import { asyncAnatomy, partAttrs, partOnlyAttrs } from '@aeon-ui/core'
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react'
+import { mergeProps } from '../utils/merge-props.js'
+import { useAsyncContext } from './context.js'
+
+export interface AsyncReadoutProps extends HTMLAttributes<HTMLDivElement> {
+  children?: ReactNode
+}
+
+export const AsyncReadout = forwardRef<HTMLDivElement, AsyncReadoutProps>(function AsyncReadout(
+  { children, className, ...rest },
+  ref,
+) {
+  const { stateAttr } = useAsyncContext()
+
+  return (
+    <div
+      ref={ref}
+      role="status"
+      aria-live="polite"
+      className={className}
+      {...mergeProps(partAttrs(asyncAnatomy.scope, asyncAnatomy.readout, { state: stateAttr }), rest)}
+    >
+      <span
+        className="aeon-async-readout__rail"
+        aria-hidden
+        {...partOnlyAttrs(asyncAnatomy.readoutRail)}
+      />
+      <div className="aeon-async-readout__body" {...partOnlyAttrs(asyncAnatomy.readoutBody)}>
+        {children}
+      </div>
+    </div>
+  )
+})

package/packages/react/src/async/root.tsx

@@ -0,0 +1,39 @@
+import { asyncAnatomy, partAttrs } from '@aeon-ui/core'
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react'
+import { mergeProps } from '../utils/merge-props.js'
+import { AsyncProvider, useAsyncContext } from './context.js'
+
+export interface AsyncRootProps extends HTMLAttributes<HTMLDivElement> {
+  children: ReactNode
+  className?: string
+}
+
+const AsyncRootInner = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(function AsyncRootInner(
+  { children, className, ...rest },
+  ref,
+) {
+  const { stateAttr } = useAsyncContext()
+
+  return (
+    <div
+      ref={ref}
+      className={className}
+      {...mergeProps(partAttrs(asyncAnatomy.scope, asyncAnatomy.root, { state: stateAttr }), rest)}
+    >
+      {children}
+    </div>
+  )
+})
+
+export const AsyncRoot = forwardRef<HTMLDivElement, AsyncRootProps>(function AsyncRoot(
+  { children, className, ...rest },
+  ref,
+) {
+  return (
+    <AsyncProvider>
+      <AsyncRootInner ref={ref} className={className} {...rest}>
+        {children}
+      </AsyncRootInner>
+    </AsyncProvider>
+  )
+})

package/packages/react/src/async/track.tsx

@@ -0,0 +1,59 @@
+import { asyncAnatomy, partOnlyAttrs } from '@aeon-ui/core'
+import { ASYNC_LIFECYCLE_STATES } from '@aeon-ui/primitives'
+import { forwardRef, type CSSProperties, type HTMLAttributes } from 'react'
+import { mergeProps } from '../utils/merge-props.js'
+import { useAsyncContext } from './context.js'
+
+type SegmentPhase = 'past' | 'active' | 'future'
+
+function segmentPhase(index: number, activeIndex: number): SegmentPhase {
+  if (activeIndex === -1) return 'future'
+  if (index === activeIndex) return 'active'
+  if (index < activeIndex) return 'past'
+  return 'future'
+}
+
+export interface AsyncTrackProps extends HTMLAttributes<HTMLDivElement> {
+  states?: readonly string[]
+}
+
+export const AsyncTrack = forwardRef<HTMLDivElement, AsyncTrackProps>(function AsyncTrack(
+  { states = ASYNC_LIFECYCLE_STATES, className, ...rest },
+  ref,
+) {
+  const { status } = useAsyncContext()
+  const activeIndex = states.indexOf(status)
+  const { style, ...restWithoutStyle } = rest
+
+  return (
+    <div
+      ref={ref}
+      role="list"
+      aria-label="Async lifecycle states"
+      className={className}
+      style={
+        {
+          ...style,
+          ['--aeon-state-track-count' as string]: states.length,
+        } as CSSProperties
+      }
+      {...mergeProps(partOnlyAttrs(asyncAnatomy.track), restWithoutStyle)}
+    >
+      {states.map((id, index) => {
+        const phase = segmentPhase(index, activeIndex)
+        return (
+          <span
+            key={id}
+            role="listitem"
+            aria-current={phase === 'active' ? 'step' : undefined}
+            title={id}
+            className={`state-track__seg state-track__seg--${id} state-track__seg--${phase}`}
+            {...partOnlyAttrs(asyncAnatomy.segment, { state: `${id} ${phase}` })}
+          >
+            {id}
+          </span>
+        )
+      })}
+    </div>
+  )
+})

package/packages/react/src/avatar/avatar.test.tsx

@@ -0,0 +1,27 @@
+import { render, screen } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+import { Avatar } from './index.js'
+
+describe('Avatar', () => {
+  it('shows fallback until image loads', () => {
+    render(
+      <Avatar.Root>
+        <Avatar.Image src="/photo.jpg" alt="User" />
+        <Avatar.Fallback>AB</Avatar.Fallback>
+      </Avatar.Root>,
+    )
+
+    expect(screen.getByText('AB')).toBeVisible()
+    expect(document.querySelector('[data-aeon-part="image"]')).toHaveAttribute('hidden')
+  })
+
+  it('shows fallback when there is no src', () => {
+    render(
+      <Avatar.Root>
+        <Avatar.Fallback>?</Avatar.Fallback>
+      </Avatar.Root>,
+    )
+
+    expect(screen.getByText('?')).toBeVisible()
+  })
+})