aeon-ui-engine 1.0.0

package/packages/panda/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "noEmit": true
+  },
+  "include": ["panda.config.ts", "src/**/*.ts"]
+}

package/packages/primitives/README.md

@@ -0,0 +1,54 @@
+# @aeon-ui/primitives
+
+**XState v5 machines** — behavior only, no DOM.
+
+Agents: [docs/MACHINES.md](../../docs/MACHINES.md) lists every machine and events.
+
+## Install
+
+```bash
+pnpm add @aeon-ui/primitives
+```
+
+Pair with `@aeon-ui/react` (`useAeonMachine`) or your own XState bindings.
+
+## Exported machines
+
+| Export | File | Use |
+|--------|------|-----|
+| `toggleMachine` | `machines/toggle.ts` | Switch, Checkbox |
+| `dialogMachine` | `machines/dialog.ts` | Dialog |
+| `tabsMachine` | `machines/tabs.ts` | Tabs |
+| `accordionMachine` | `machines/accordion.ts` | Accordion |
+| `createAsyncMachine` | `machines/async.ts` | Async regions |
+| `asyncMachine` | default instance | |
+| `buttonLifecycleMachine` | `machines/button.ts` | App/demo — not wired inside headless Button |
+| `fieldMachine` | `machines/field.ts` | Field (parallel) |
+| `popoverMachine` | `machines/popover.ts` | Menu, Popover, Select |
+| `toastMachine` | `machines/toast.ts` | Toast item |
+
+## Helpers
+
+```ts
+import { ASYNC_LIFECYCLE_STATES, isEmptyAsyncData, createAsyncMachine } from '@aeon-ui/primitives'
+```
+
+## Async example
+
+```ts
+const machine = createAsyncMachine<User[]>()
+// send: FETCH | RESOLVE | REJECT | RESET | STALE | REFRESH
+```
+
+## Extend
+
+1. Add `src/machines/<name>.ts`
+2. Export from `src/index.ts`
+3. Wire in `@aeon-ui/react`
+4. Update `apps/demo/src/aeonDiagrams.ts`
+5. [docs/COMPONENT_CHECKLIST.md](../../docs/COMPONENT_CHECKLIST.md)
+
+## Related
+
+- [STATES.md](../../STATES.md)
+- [packages/react/README.md](../react/README.md)

package/packages/primitives/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@aeon-ui/primitives",
+  "version": "0.1.0",
+  "description": "XState machines for Aeon UI primitives",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GenericCPU/aeon-ui.git",
+    "directory": "packages/primitives"
+  },
+  "publishConfig": { "access": "public" },
+  "files": ["dist", "README.md"],
+  "keywords": ["aeon-ui", "xstate", "statechart", "machines"],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./machines/*": {
+      "types": "./dist/machines/*.d.ts",
+      "import": "./dist/machines/*.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/machines/*.ts --format esm --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@aeon-ui/core": "workspace:*",
+    "xstate": "^5.19.2"
+  },
+  "devDependencies": {
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  }
+}

package/packages/primitives/src/__tests__/floating-surface.test.ts

@@ -0,0 +1,29 @@
+import { createActor } from 'xstate'
+import { describe, expect, it } from 'vitest'
+import { dialogMachine } from '../machines/dialog.js'
+import { popoverMachine } from '../machines/popover.js'
+
+const machines = [
+  { name: 'popoverMachine', machine: popoverMachine, input: { open: false } },
+  { name: 'dialogMachine', machine: dialogMachine, input: { open: false } },
+] as const
+
+describe.each(machines)('$name', ({ machine, input }) => {
+  it('opens on TOGGLE and closes on outside pointer', () => {
+    const actor = createActor(machine, { input })
+    actor.start()
+    actor.send({ type: 'TOGGLE' })
+    expect(actor.getSnapshot().matches('open')).toBe(true)
+    actor.send({ type: 'POINTER_DOWN_OUTSIDE' })
+    expect(actor.getSnapshot().matches('closed')).toBe(true)
+  })
+
+  it('respects controlled SET_OPEN', () => {
+    const actor = createActor(machine, { input })
+    actor.start()
+    actor.send({ type: 'SET_OPEN', open: true })
+    expect(actor.getSnapshot().matches('open')).toBe(true)
+    actor.send({ type: 'SET_OPEN', open: false })
+    expect(actor.getSnapshot().matches('closed')).toBe(true)
+  })
+})

package/packages/primitives/src/index.ts

@@ -0,0 +1,9 @@
+export * from './machines/toggle.js'
+export * from './machines/dialog.js'
+export * from './machines/tabs.js'
+export * from './machines/accordion.js'
+export * from './machines/async.js'
+export * from './machines/button.js'
+export * from './machines/field.js'
+export * from './machines/popover.js'
+export * from './machines/toast.js'

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

@@ -0,0 +1,56 @@
+import { assign, setup } from 'xstate'
+
+export interface AccordionContext {
+  value: string[]
+  multiple: boolean
+  collapsible: boolean
+}
+
+export type AccordionEvent =
+  | { type: 'TOGGLE'; item: string }
+  | { type: 'SET_VALUE'; value: string[] }
+
+function toggleItem(items: string[], item: string, multiple: boolean, collapsible: boolean) {
+  const isOpen = items.includes(item)
+  if (!multiple) {
+    if (isOpen) return collapsible ? [] : items
+    return [item]
+  }
+  if (isOpen) return items.filter((i) => i !== item)
+  return [...items, item]
+}
+
+export const accordionMachine = setup({
+  types: {
+    context: {} as AccordionContext,
+    events: {} as AccordionEvent,
+    input: {} as AccordionContext,
+  },
+  actions: {
+    toggle: assign({
+      value: ({ context, event }) =>
+        event.type === 'TOGGLE'
+          ? toggleItem(context.value, event.item, context.multiple, context.collapsible)
+          : context.value,
+    }),
+    setValue: assign({
+      value: ({ event }) => (event.type === 'SET_VALUE' ? event.value : []),
+    }),
+  },
+}).createMachine({
+  id: 'accordion',
+  context: ({ input }) => ({
+    value: input.value ?? [],
+    multiple: input.multiple ?? false,
+    collapsible: input.collapsible ?? true,
+  }),
+  initial: 'managing',
+  states: {
+    managing: {
+      on: {
+        TOGGLE: { actions: 'toggle' },
+        SET_VALUE: { actions: 'setValue' },
+      },
+    },
+  },
+})

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

@@ -0,0 +1,108 @@
+import { assign, setup } from 'xstate'
+
+/** Stable lifecycle states for async data regions (see STATES.md). */
+export const ASYNC_LIFECYCLE_STATES = [
+  'idle',
+  'loading',
+  'success',
+  'failure',
+  'empty',
+] as const
+
+export type AsyncLifecycleState = (typeof ASYNC_LIFECYCLE_STATES)[number]
+
+export function isEmptyAsyncData(data: unknown): boolean {
+  if (data == null) return true
+  if (typeof data === 'string') return data.length === 0
+  if (Array.isArray(data)) return data.length === 0
+  return false
+}
+
+/**
+ * Thesis §2.1: fetch lifecycle as sequential, well-defined states.
+ * This machine models fetch lifecycle as mutually exclusive states.
+ */
+export interface AsyncContext<T = unknown> {
+  data: T | null
+  error: string | null
+  /** Success with background refresh — style readout as `success stale` (see STATES.md). */
+  stale?: boolean
+}
+
+export type AsyncEvent<T = unknown> =
+  | { type: 'FETCH' }
+  | { type: 'RESOLVE'; data: T }
+  | { type: 'REJECT'; error: string }
+  | { type: 'RESET' }
+  | { type: 'STALE' }
+  | { type: 'REFRESH' }
+
+export function createAsyncMachine<T = unknown>() {
+  return setup({
+    types: {
+      context: {} as AsyncContext<T>,
+      events: {} as AsyncEvent<T>,
+    },
+    actions: {
+      clear: assign({ data: null, error: null }),
+      resolve: assign({
+        data: ({ event }) => (event.type === 'RESOLVE' ? event.data : null),
+        error: null,
+        stale: false,
+      }),
+      markStale: assign({ stale: true }),
+      clearStale: assign({ stale: false }),
+      reject: assign({
+        error: ({ event }) => (event.type === 'REJECT' ? event.error : null),
+        data: null,
+      }),
+    },
+  }).createMachine({
+    id: 'async',
+    context: { data: null, error: null },
+    initial: 'idle',
+    states: {
+      idle: {
+        on: {
+          FETCH: 'loading',
+          RESET: { actions: 'clear' },
+        },
+      },
+      loading: {
+        on: {
+          RESOLVE: [
+            {
+              target: 'empty',
+              actions: 'resolve',
+              guard: ({ event }) => event.type === 'RESOLVE' && isEmptyAsyncData(event.data),
+            },
+            { target: 'success', actions: 'resolve' },
+          ],
+          REJECT: { target: 'failure', actions: 'reject' },
+        },
+      },
+      empty: {
+        on: {
+          FETCH: 'loading',
+          RESET: { target: 'idle', actions: 'clear' },
+        },
+      },
+      success: {
+        on: {
+          FETCH: { target: 'loading', actions: 'clearStale' },
+          STALE: { actions: 'markStale' },
+          REFRESH: { actions: 'clearStale' },
+          RESET: { target: 'idle', actions: 'clear' },
+        },
+      },
+      failure: {
+        on: {
+          FETCH: 'loading',
+          RESET: { target: 'idle', actions: 'clear' },
+        },
+      },
+    },
+  })
+}
+
+export const asyncMachine = createAsyncMachine()

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

@@ -0,0 +1,66 @@
+import { setup } from 'xstate'
+
+export const BUTTON_LIFECYCLE_STATES = [
+  'idle',
+  'pending',
+  'success',
+  'failure',
+  'disabled',
+] as const
+
+export type ButtonLifecycleState = (typeof BUTTON_LIFECYCLE_STATES)[number]
+
+export type ButtonLifecycleEvent =
+  | { type: 'PRESS' }
+  | { type: 'SUCCEED' }
+  | { type: 'FAIL' }
+  | { type: 'RESET' }
+  | { type: 'DISABLE' }
+  | { type: 'ENABLE' }
+
+/**
+ * Submit / action button lifecycle — idle → pending → success | failure.
+ * Use for controls that represent an in-flight operation, not mere `disabled`.
+ */
+export const buttonLifecycleMachine = setup({
+  types: {
+    events: {} as ButtonLifecycleEvent,
+  },
+}).createMachine({
+  id: 'buttonLifecycle',
+  initial: 'idle',
+  states: {
+    idle: {
+      on: {
+        PRESS: 'pending',
+        DISABLE: 'disabled',
+      },
+    },
+    pending: {
+      on: {
+        SUCCEED: 'success',
+        FAIL: 'failure',
+        DISABLE: 'disabled',
+      },
+    },
+    success: {
+      on: {
+        RESET: 'idle',
+        PRESS: 'pending',
+        DISABLE: 'disabled',
+      },
+    },
+    failure: {
+      on: {
+        RESET: 'idle',
+        PRESS: 'pending',
+        DISABLE: 'disabled',
+      },
+    },
+    disabled: {
+      on: {
+        ENABLE: 'idle',
+      },
+    },
+  },
+})

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

@@ -0,0 +1,61 @@
+import { assign, setup } from 'xstate'
+
+export interface DialogContext {
+  open: boolean
+}
+
+export type DialogEvent =
+  | { type: 'OPEN' }
+  | { type: 'CLOSE' }
+  | { type: 'TOGGLE' }
+  | { type: 'SET_OPEN'; open: boolean }
+  | { type: 'ESCAPE' }
+  | { type: 'POINTER_DOWN_OUTSIDE' }
+
+/**
+ * Dialog visibility is a single orthogonal region: closed | open.
+ * Open and closed are distinct, stable states.
+ */
+export const dialogMachine = setup({
+  types: {
+    context: {} as DialogContext,
+    events: {} as DialogEvent,
+    input: {} as DialogContext,
+  },
+  actions: {
+    markOpen: assign({ open: true }),
+    markClosed: assign({ open: false }),
+    toggleOpen: assign({ open: ({ context }) => !context.open }),
+    setOpen: assign({
+      open: ({ event }) => (event.type === 'SET_OPEN' ? event.open : false),
+    }),
+  },
+}).createMachine({
+  id: 'dialog',
+  context: ({ input }) => ({
+    open: input.open ?? false,
+  }),
+  initial: 'closed',
+  states: {
+    closed: {
+      on: {
+        OPEN: { target: 'open', actions: 'markOpen' },
+        TOGGLE: { target: 'open', actions: 'markOpen' },
+        SET_OPEN: [
+          { target: 'open', actions: 'markOpen', guard: ({ event }) => event.open },
+        ],
+      },
+    },
+    open: {
+      on: {
+        CLOSE: { target: 'closed', actions: 'markClosed' },
+        ESCAPE: { target: 'closed', actions: 'markClosed' },
+        POINTER_DOWN_OUTSIDE: { target: 'closed', actions: 'markClosed' },
+        TOGGLE: { target: 'closed', actions: 'markClosed' },
+        SET_OPEN: [
+          { target: 'closed', actions: 'markClosed', guard: ({ event }) => !event.open },
+        ],
+      },
+    },
+  },
+})

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

@@ -0,0 +1,85 @@
+import { setup } from 'xstate'
+
+export const FIELD_INTERACTION_STATES = ['pristine', 'dirty'] as const
+export const FIELD_VALIDATION_STATES = ['valid', 'invalid'] as const
+export const FIELD_SUBMISSION_STATES = ['idle', 'pending'] as const
+
+export type FieldInteractionState = (typeof FIELD_INTERACTION_STATES)[number]
+export type FieldValidationState = (typeof FIELD_VALIDATION_STATES)[number]
+export type FieldSubmissionState = (typeof FIELD_SUBMISSION_STATES)[number]
+
+export type FieldEvent =
+  | { type: 'INPUT' }
+  | { type: 'BLUR' }
+  | { type: 'VALIDATE'; valid: boolean }
+  | { type: 'SUBMIT' }
+  | { type: 'SUBMIT_DONE' }
+  | { type: 'SUBMIT_FAIL' }
+  | { type: 'RESET' }
+
+/**
+ * Orthogonal field regions — interaction, validation, and submission evolve independently.
+ * Snapshot value is nested; flatten with `stateToAttr` for `data-aeon-state`.
+ */
+export const fieldMachine = setup({
+  types: {
+    events: {} as FieldEvent,
+  },
+}).createMachine({
+  id: 'field',
+  type: 'parallel',
+  states: {
+    interaction: {
+      initial: 'pristine',
+      states: {
+        pristine: {
+          on: {
+            INPUT: 'dirty',
+            BLUR: 'dirty',
+          },
+        },
+        dirty: {
+          on: {
+            RESET: 'pristine',
+          },
+        },
+      },
+    },
+    validation: {
+      initial: 'valid',
+      states: {
+        valid: {
+          on: {
+            VALIDATE: [
+              { target: 'invalid', guard: ({ event }) => event.type === 'VALIDATE' && !event.valid },
+            ],
+          },
+        },
+        invalid: {
+          on: {
+            VALIDATE: [
+              { target: 'valid', guard: ({ event }) => event.type === 'VALIDATE' && event.valid },
+            ],
+            RESET: 'valid',
+          },
+        },
+      },
+    },
+    submission: {
+      initial: 'idle',
+      states: {
+        idle: {
+          on: {
+            SUBMIT: 'pending',
+          },
+        },
+        pending: {
+          on: {
+            SUBMIT_DONE: 'idle',
+            SUBMIT_FAIL: 'idle',
+          },
+        },
+      },
+    },
+  },
+})

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

@@ -0,0 +1,52 @@
+import { assign, setup } from 'xstate'
+
+export interface PopoverContext {
+  open: boolean
+}
+
+export type PopoverEvent =
+  | { type: 'OPEN' }
+  | { type: 'CLOSE' }
+  | { type: 'TOGGLE' }
+  | { type: 'SET_OPEN'; open: boolean }
+  | { type: 'ESCAPE' }
+  | { type: 'POINTER_DOWN_OUTSIDE' }
+
+/** Floating surface: menu, popover, select listbox — closed | open. */
+export const popoverMachine = setup({
+  types: {
+    context: {} as PopoverContext,
+    events: {} as PopoverEvent,
+    input: {} as PopoverContext,
+  },
+  actions: {
+    markOpen: assign({ open: true }),
+    markClosed: assign({ open: false }),
+    toggleOpen: assign({ open: ({ context }) => !context.open }),
+    setOpen: assign({
+      open: ({ event }) => (event.type === 'SET_OPEN' ? event.open : false),
+    }),
+  },
+}).createMachine({
+  id: 'popover',
+  context: ({ input }) => ({ open: input.open ?? false }),
+  initial: 'closed',
+  states: {
+    closed: {
+      on: {
+        OPEN: { target: 'open', actions: 'markOpen' },
+        TOGGLE: { target: 'open', actions: 'markOpen' },
+        SET_OPEN: [{ target: 'open', actions: 'markOpen', guard: ({ event }) => event.open }],
+      },
+    },
+    open: {
+      on: {
+        CLOSE: { target: 'closed', actions: 'markClosed' },
+        ESCAPE: { target: 'closed', actions: 'markClosed' },
+        POINTER_DOWN_OUTSIDE: { target: 'closed', actions: 'markClosed' },
+        TOGGLE: { target: 'closed', actions: 'markClosed' },
+        SET_OPEN: [{ target: 'closed', actions: 'markClosed', guard: ({ event }) => !event.open }],
+      },
+    },
+  },
+})

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

@@ -0,0 +1,46 @@
+import { assign, setup } from 'xstate'
+
+export interface TabsContext {
+  value: string
+  disabled: boolean
+}
+
+export type TabsEvent =
+  | { type: 'SELECT'; value: string }
+  | { type: 'SET_VALUE'; value: string }
+
+export const tabsMachine = setup({
+  types: {
+    context: {} as TabsContext,
+    events: {} as TabsEvent,
+    input: {} as TabsContext,
+  },
+  guards: {
+    notDisabled: ({ context }) => !context.disabled,
+    hasValue: ({ event }) => event.type === 'SELECT' && Boolean(event.value),
+  },
+  actions: {
+    select: assign({
+      value: ({ event }) => (event.type === 'SELECT' ? event.value : ''),
+    }),
+    setValue: assign({
+      value: ({ event }) => (event.type === 'SET_VALUE' ? event.value : ''),
+    }),
+  },
+}).createMachine({
+  id: 'tabs',
+  context: ({ input }) => ({
+    value: input.value ?? '',
+    disabled: input.disabled ?? false,
+  }),
+  /** Single stable region: which trigger is active. */
+  initial: 'active',
+  states: {
+    active: {
+      on: {
+        SELECT: { actions: 'select', guard: 'hasValue' },
+        SET_VALUE: { actions: 'setValue' },
+      },
+    },
+  },
+})

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

@@ -0,0 +1,48 @@
+import { setup } from 'xstate'
+
+export interface ToastContext {
+  durationMs: number
+}
+
+export type ToastEvent =
+  | { type: 'SHOW' }
+  | { type: 'DISMISS' }
+  | { type: 'TIMEOUT' }
+
+/** Toast lifecycle: hidden → visible → hidden (dismiss or auto timeout). */
+export const toastMachine = setup({
+  types: {
+    context: {} as ToastContext,
+    events: {} as ToastEvent,
+    input: {} as ToastContext,
+  },
+  guards: {
+    hasDuration: ({ context }) => context.durationMs > 0,
+  },
+  delays: {
+    VISIBLE_TIMEOUT: ({ context }) => context.durationMs,
+  },
+}).createMachine({
+  id: 'toast',
+  context: ({ input }) => ({ durationMs: input.durationMs ?? 5000 }),
+  initial: 'hidden',
+  states: {
+    hidden: {
+      on: {
+        SHOW: 'visible',
+      },
+    },
+    visible: {
+      on: {
+        DISMISS: 'hidden',
+        TIMEOUT: 'hidden',
+      },
+      after: {
+        VISIBLE_TIMEOUT: {
+          target: 'hidden',
+          guard: 'hasDuration',
+        },
+      },
+    },
+  },
+})