aeon-ui-engine 1.0.0

package/docs/VITE_CONSUMER.md

@@ -0,0 +1,114 @@
+# Vite apps (headless, no Panda)
+
+Use this for marketing sites and HandCash apps that keep their own CSS and only need `@aeon-ui/react`.
+
+## 1. Install runtime deps
+
+```bash
+npm install @xstate/react xstate
+```
+
+After `@aeon-ui/*` is on npm, also:
+
+```bash
+npm install @aeon-ui/react @aeon-ui/core @aeon-ui/primitives
+```
+
+Until publish, point Vite at a local clone (see below).
+
+## 2. Ensure packages are built
+
+From the Aeon UI repo:
+
+```bash
+pnpm run build:headless
+```
+
+Or from any consumer `package.json`:
+
+```json
+{
+  "scripts": {
+    "aeon:ensure": "node ../path/to/AeonUI/scripts/ensure-headless-built.mjs",
+    "prebuild": "npm run aeon:ensure && vite build"
+  }
+}
+```
+
+Set `AEON_UI_ROOT` in CI when the monorepo is not at `~/AeonUI`.
+
+## 3. Vite aliases (local clone)
+
+```ts
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = path.dirname(fileURLToPath(import.meta.url))
+const aeonRoot = process.env.AEON_UI_ROOT ?? path.resolve(root, '../../../AeonUI')
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      '@aeon-ui/core': path.join(aeonRoot, 'packages/core/dist/index.js'),
+      '@aeon-ui/primitives': path.join(aeonRoot, 'packages/primitives/dist/index.js'),
+      '@aeon-ui/react': path.join(aeonRoot, 'packages/react/dist/index.js'),
+    },
+  },
+  optimizeDeps: {
+    include: ['@aeon-ui/react', '@aeon-ui/core', '@aeon-ui/primitives', 'xstate', '@xstate/react'],
+  },
+})
+```
+
+Adjust `../../../AeonUI` to your layout.
+
+## 4. TypeScript paths
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "@aeon-ui/core": ["../../../AeonUI/packages/core/dist/index.d.ts"],
+      "@aeon-ui/primitives": ["../../../AeonUI/packages/primitives/dist/index.d.ts"],
+      "@aeon-ui/react": ["../../../AeonUI/packages/react/dist/index.d.ts"]
+    }
+  }
+}
+```
+
+## 5. Style with data-aeon-*
+
+```css
+[data-aeon-scope='field'][data-aeon-part='control'],
+[data-aeon-scope='field'][data-aeon-part='textarea'] {
+  /* shared input styles */
+}
+```
+
+See [INTEGRATION.md](../INTEGRATION.md) and [STATES.md](../STATES.md).
+
+## 6. Toasts
+
+Wrap the app (or layout) once:
+
+```tsx
+import { Toast } from '@aeon-ui/react'
+
+<Toast.Provider>
+  <App />
+  <Toast.Viewport placement="bottom-end" />
+</Toast.Provider>
+```
+
+Publish from anywhere under the tree:
+
+```tsx
+const { publish } = useToast()
+publish({ title: 'Saved', description: 'Changes are live.' })
+```
+
+## 7. Migrating from Ark UI
+
+Full guide: **[MIGRATION_FROM_ARK.md](./MIGRATION_FROM_ARK.md)** (inventory, Next.js, Select/Dialog/Toast/Avatar, CSS selectors, verification).
+
+Reference consumers: **spidercorp.xyz** (Vite), **soundbase.click** (Next.js).

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "aeon-ui-engine",
+  "version": "1.0.0",
+  "private": false,
+  "scripts": {
+    "build": "pnpm --filter @aeon-ui/panda run codegen && pnpm -r run build",
+    "build:headless": "pnpm --filter @aeon-ui/core --filter @aeon-ui/primitives --filter @aeon-ui/react run build",
+    "codegen": "pnpm --filter @aeon-ui/panda codegen",
+    "dev": "pnpm --filter @aeon-ui/demo dev",
+    "typecheck": "pnpm -r run typecheck",
+    "test": "pnpm run test:headless",
+    "test:headless": "pnpm run build:headless && pnpm --filter @aeon-ui/core --filter @aeon-ui/primitives --filter @aeon-ui/react run test",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "pnpm build && changeset publish"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.29.0",
+    "typescript": "^5.8.3"
+  },
+  "packageManager": "pnpm@10.11.0",
+  "engines": {
+    "node": ">=20"
+  }
+}

package/packages/core/README.md

@@ -0,0 +1,69 @@
+# @aeon-ui/core
+
+**DOM contract and anatomy** — no React, no XState runtime in components.
+
+Agents: read [AGENTS.md](../../AGENTS.md) and [docs/FILE_MAP.md](../../docs/FILE_MAP.md).
+
+## Install
+
+```bash
+pnpm add @aeon-ui/core
+```
+
+Usually consumed via `@aeon-ui/react` or `@aeon-ui/ui`.
+
+## Exports
+
+| Module | Purpose |
+|--------|---------|
+| `philosophy` | `UI_IS_FUNCTION_OF_STATE`, `AEON_PRINCIPLE` |
+| `anatomy` | `buttonAnatomy`, `asyncAnatomy`, `fieldAnatomy`, … |
+| `attrs` | `partAttrs`, `scopeAttrs`, `partOnlyAttrs`, `stateToAttr` |
+| `machine` | `createAeonMachine` — XState `setup` helper |
+| `scroll` | `getScrollSnapshot(element)` |
+| `layout` | Normalized coords, `ResponsiveLayoutSpec`, `layoutModeAttrs` |
+| `types` | Shared types |
+
+### Play-surface layout (coordinates)
+
+```ts
+import {
+  playSurfaceAnatomy,
+  normFromClient,
+  layoutModeAttrs,
+  type ResponsiveLayoutSpec,
+} from '@aeon-ui/core'
+```
+
+See [docs/LAYOUT_COORDINATES.md](../../docs/LAYOUT_COORDINATES.md).
+
+## Anatomy
+
+```ts
+import { asyncAnatomy, partAttrs } from '@aeon-ui/core'
+
+partAttrs(asyncAnatomy.scope, asyncAnatomy.readout, {
+  state: 'loading',
+})
+// → data-aeon-scope="async" data-aeon-part="readout" data-aeon-state="loading"
+```
+
+## Parallel regions
+
+```ts
+import { stateToAttr } from '@aeon-ui/core'
+
+stateToAttr({ interaction: 'dirty', validation: 'invalid', submission: 'idle' })
+// → "interaction:dirty validation:invalid submission:idle"
+```
+
+## Adding a scope
+
+1. Add `myAnatomy = anatomy('my', ['root', ...] as const)` in `src/anatomy.ts`.
+2. Use in React via `partAttrs`.
+3. Follow [docs/COMPONENT_CHECKLIST.md](../../docs/COMPONENT_CHECKLIST.md).
+
+## Related
+
+- [STATES.md](../../STATES.md) — attribute contract
+- [packages/primitives/README.md](../primitives/README.md) — machines

package/packages/core/package.json

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

package/packages/core/src/anatomy.ts

@@ -0,0 +1,144 @@
+/** Part keys for compound components — scope + named parts for styling and docs. */
+export function anatomy<const T extends readonly string[]>(scope: string, parts: T) {
+  return Object.fromEntries(parts.map((p) => [p, p])) as Record<T[number], T[number]> & {
+    scope: typeof scope
+  }
+}
+
+export const buttonAnatomy = anatomy('button', [
+  'root',
+  'group',
+  'label',
+  'icon',
+] as const)
+
+export const switchAnatomy = anatomy('switch', [
+  'root',
+  'control',
+  'thumb',
+  'label',
+  'hiddenInput',
+] as const)
+
+export const checkboxAnatomy = anatomy('checkbox', [
+  'root',
+  'control',
+  'indicator',
+  'label',
+  'hiddenInput',
+] as const)
+
+export const dialogAnatomy = anatomy('dialog', [
+  'root',
+  'trigger',
+  'portal',
+  'backdrop',
+  'positioner',
+  'content',
+  'title',
+  'description',
+  'closeTrigger',
+] as const)
+
+export const tabsAnatomy = anatomy('tabs', [
+  'root',
+  'list',
+  'trigger',
+  'content',
+  'indicator',
+] as const)
+
+export const accordionAnatomy = anatomy('accordion', [
+  'root',
+  'item',
+  'itemTrigger',
+  'itemContent',
+  'itemIndicator',
+] as const)
+
+/** Async data region — track shows every lifecycle state; readout + actions mirror snapshot. */
+export const asyncAnatomy = anatomy('async', [
+  'root',
+  'track',
+  'segment',
+  'readout',
+  'readoutRail',
+  'readoutBody',
+  'actions',
+] as const)
+
+/** Form field — orthogonal interaction × validation × submission (see STATES.md). */
+export const fieldAnatomy = anatomy('field', [
+  'root',
+  'label',
+  'control',
+  'textarea',
+  'message',
+  'hint',
+] as const)
+
+/** Scroll viewport — overflow axis + edge position on data-aeon-state. */
+export const scrollAnatomy = anatomy('scroll', ['root', 'viewport', 'content'] as const)
+
+/**
+ * Play / game surface — mat shell with table, dice, and bank regions.
+ * Use with normalized layout coords (@see docs/LAYOUT_COORDINATES.md).
+ */
+export const playSurfaceAnatomy = anatomy('play', ['mat', 'table', 'dice', 'bank'] as const)
+
+export const selectAnatomy = anatomy('select', [
+  'root',
+  'trigger',
+  'value',
+  'icon',
+  'positioner',
+  'content',
+  'item',
+] as const)
+
+/** Typeahead listbox — extends select with filter input and empty state. */
+export const comboboxAnatomy = anatomy('combobox', [
+  'root',
+  'input',
+  'icon',
+  'content',
+  'item',
+  'empty',
+] as const)
+
+export const popoverAnatomy = anatomy('popover', [
+  'root',
+  'trigger',
+  'positioner',
+  'content',
+  'arrow',
+  'closeTrigger',
+] as const)
+
+export const menuAnatomy = anatomy('menu', [
+  'root',
+  'trigger',
+  'positioner',
+  'content',
+  'item',
+  'separator',
+] as const)
+
+export const tooltipAnatomy = anatomy('tooltip', [
+  'root',
+  'trigger',
+  'positioner',
+  'content',
+  'arrow',
+] as const)
+
+export const toastAnatomy = anatomy('toast', [
+  'viewport',
+  'root',
+  'title',
+  'description',
+  'closeTrigger',
+] as const)
+
+/** Profile image — loaded / loading / error on root `data-aeon-state`. */
+export const avatarAnatomy = anatomy('avatar', ['root', 'image', 'fallback'] as const)

package/packages/core/src/attrs.ts

@@ -0,0 +1,47 @@
+type AttrOptions = {
+  state?: string | string[]
+  disabled?: boolean
+  focus?: boolean
+  highlighted?: boolean
+}
+
+function stateFields(options?: AttrOptions) {
+  const states = options?.state
+    ? Array.isArray(options.state)
+      ? options.state.join(' ')
+      : options.state
+    : undefined
+
+  return {
+    ...(states ? { 'data-aeon-state': states } : {}),
+    ...(options?.disabled ? { 'data-disabled': '' } : {}),
+    ...(options?.focus ? { 'data-focus': '' } : {}),
+    ...(options?.highlighted ? { 'data-highlighted': '' } : {}),
+  }
+}
+
+/** Scope + part on the component root (e.g. accordion root). */
+export function scopeAttrs(
+  scope: string,
+  part = 'root',
+  options?: AttrOptions,
+): Record<string, unknown> {
+  return {
+    'data-aeon-scope': scope,
+    'data-aeon-part': part,
+    ...stateFields(options),
+  }
+}
+
+/** Part only — use on children inside a scoped root. */
+export function partOnlyAttrs(part: string, options?: AttrOptions): Record<string, unknown> {
+  return {
+    'data-aeon-part': part,
+    ...stateFields(options),
+  }
+}
+
+/** Build data-aeon-* attributes for styling unstyled parts. */
+export function partAttrs(scope: string, part: string, options?: AttrOptions): Record<string, unknown> {
+  return scopeAttrs(scope, part, options)
+}

package/packages/core/src/index.ts

@@ -0,0 +1,8 @@
+export * from './philosophy.js'
+export * from './anatomy.js'
+export * from './attrs.js'
+export * from './machine.js'
+export * from './types.js'
+export * from './scroll.js'
+export * from './layout.js'
+export * from './theme.js'

package/packages/core/src/layout.ts

@@ -0,0 +1,176 @@
+/**
+ * Responsive play-surface layout — logical coordinate plane + composition modes.
+ *
+ * Behavior stays in statecharts; **where** the user points is expressed in normalized
+ * coordinates (0–100) inside a measured region, independent of CSS grid vs overlay.
+ *
+ * @see docs/LAYOUT_COORDINATES.md
+ */
+
+/** Point on the normalized plane (percent of region width/height). */
+export type NormPoint = { readonly x: number; readonly y: number }
+
+/** Axis-aligned bounds on the normalized plane (inclusive). */
+export type NormRect = {
+  readonly xMin: number
+  readonly xMax: number
+  readonly yMin: number
+  readonly yMax: number
+}
+
+/** DOM mapping: y increases upward (throws, dice) vs downward (top-left UI). */
+export type NormOrigin = 'bottom-left' | 'top-left'
+
+export const NORM_PLANE = {
+  bottomLeft: 'bottom-left',
+  topLeft: 'top-left',
+} as const satisfies Record<string, NormOrigin>
+
+/** How regions are composed at a breakpoint — product maps to CSS grid / absolute. */
+export type LayoutComposition = 'split' | 'stack' | 'overlay'
+
+export interface RegionLayoutSlot {
+  /** Logical region id (matches anatomy part or app constant). */
+  readonly region: string
+  /** Grid area name / slot id for CSS `grid-template-areas`. */
+  readonly slot: string
+  readonly zIndex?: number
+}
+
+export interface LayoutCompositionSpec {
+  readonly id: string
+  readonly composition: LayoutComposition
+  readonly regions: readonly RegionLayoutSlot[]
+  /** Interaction bounds per region in **that region's** normalized plane. */
+  readonly bounds?: Readonly<Record<string, NormRect>>
+}
+
+export type LayoutMode = 'compact' | 'wide'
+
+export interface ResponsiveLayoutSpec {
+  readonly modes: {
+    readonly compact: LayoutCompositionSpec
+    readonly wide: LayoutCompositionSpec
+  }
+  /**
+   * Media query that selects `compact` when matched (default: phone portrait).
+   * When it does not match, mode is `wide`.
+   */
+  readonly compactMq?: string
+}
+
+export const DEFAULT_COMPACT_MQ = '(max-width: 39.99rem)'
+
+export function clampNorm(point: NormPoint, bounds: NormRect): NormPoint {
+  return {
+    x: Math.min(bounds.xMax, Math.max(bounds.xMin, point.x)),
+    y: Math.min(bounds.yMax, Math.max(bounds.yMin, point.y)),
+  }
+}
+
+export function normFromClient(
+  rect: DOMRectReadOnly,
+  clientX: number,
+  clientY: number,
+  options?: { origin?: NormOrigin; bounds?: NormRect },
+): NormPoint {
+  const origin = options?.origin ?? NORM_PLANE.bottomLeft
+  const w = rect.width || 1
+  const h = rect.height || 1
+  const x = ((clientX - rect.left) / w) * 100
+  const yFromTop = (clientY - rect.top) / h
+  const y =
+    origin === NORM_PLANE.bottomLeft ? (1 - yFromTop) * 100 : yFromTop * 100
+  const raw = { x, y }
+  return options?.bounds ? clampNorm(raw, options.bounds) : raw
+}
+
+export function clientFromNorm(
+  rect: DOMRectReadOnly,
+  point: NormPoint,
+  options?: { origin?: NormOrigin },
+): { clientX: number; clientY: number } {
+  const origin = options?.origin ?? NORM_PLANE.bottomLeft
+  const w = rect.width || 1
+  const h = rect.height || 1
+  const clientX = rect.left + (point.x / 100) * w
+  const yFromTop = origin === NORM_PLANE.bottomLeft ? 1 - point.y / 100 : point.y / 100
+  const clientY = rect.top + yFromTop * h
+  return { clientX, clientY }
+}
+
+/** Measure element; returns null if not connected. */
+export function measureElement(el: Element | null | undefined): DOMRect | null {
+  if (!el || !('getBoundingClientRect' in el)) return null
+  const rect = el.getBoundingClientRect()
+  return rect.width > 0 && rect.height > 0 ? rect : null
+}
+
+/** Prefer a dedicated region rect; fall back to mat when lane not mounted. */
+export function resolveRegionRect(
+  primary: DOMRect | null | undefined,
+  fallback: DOMRect | null | undefined,
+): DOMRect | null {
+  if (primary && primary.width > 0 && primary.height > 0) return primary
+  if (fallback && fallback.width > 0 && fallback.height > 0) return fallback
+  return null
+}
+
+export function matchLayoutMode(
+  spec: ResponsiveLayoutSpec,
+  mq: Pick<MediaQueryList, 'matches'> = getCompactMq(spec),
+): LayoutMode {
+  return mq.matches ? 'compact' : 'wide'
+}
+
+export function getCompactMq(spec: ResponsiveLayoutSpec): MediaQueryList {
+  const query = spec.compactMq ?? DEFAULT_COMPACT_MQ
+  if (typeof window === 'undefined' || !window.matchMedia) {
+    return { matches: false } as MediaQueryList
+  }
+  return window.matchMedia(query)
+}
+
+export function layoutCompositionForMode(
+  spec: ResponsiveLayoutSpec,
+  mode: LayoutMode,
+): LayoutCompositionSpec {
+  return spec.modes[mode]
+}
+
+export function regionBoundsForMode(
+  spec: ResponsiveLayoutSpec,
+  mode: LayoutMode,
+  regionId: string,
+): NormRect | undefined {
+  return spec.modes[mode].bounds?.[regionId]
+}
+
+/**
+ * Value for `data-aeon-layout-mode` on the mat root.
+ * Pair with `data-aeon-layout-composition` from the active spec.
+ */
+export function layoutModeAttrs(mode: LayoutMode, composition: LayoutComposition): Record<string, string> {
+  return {
+    'data-aeon-layout-mode': mode,
+    'data-aeon-layout-composition': composition,
+  }
+}
+
+/** Spread a norm point inside bounds (keeps cluster off edges). */
+export function insetNormCluster(
+  point: NormPoint,
+  bounds: NormRect,
+  inset: { x?: number; y?: number } = {},
+): NormPoint {
+  const padX = inset.x ?? 0
+  const padY = inset.y ?? 0
+  const halfX = (bounds.xMax - bounds.xMin) / 2
+  const halfY = (bounds.yMax - bounds.yMin) / 2
+  const capX = Math.min(padX, halfX - 0.5)
+  const capY = Math.min(padY, halfY - 0.5)
+  return {
+    x: Math.min(bounds.xMax - capX, Math.max(bounds.xMin + capX, point.x)),
+    y: Math.min(bounds.yMax - capY, Math.max(bounds.yMin + capY, point.y)),
+  }
+}

package/packages/core/src/machine.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest'
+import { stateToAttr } from './machine.js'
+
+describe('stateToAttr', () => {
+  it('stringifies string states', () => {
+    expect(stateToAttr('open')).toBe('open')
+  })
+
+  it('flattens parallel regions', () => {
+    expect(
+      stateToAttr({
+        interaction: 'dirty',
+        validation: 'invalid',
+        submission: 'idle',
+      }),
+    ).toBe('interaction:dirty validation:invalid submission:idle')
+  })
+})

package/packages/core/src/machine.ts

@@ -0,0 +1,15 @@
+import { setup, type ActorRefFrom, type AnyStateMachine, type SnapshotFrom } from 'xstate'
+
+/** Re-export XState setup — encode UI behavior as executable statecharts. */
+export { setup as createAeonMachine }
+
+export type AeonSnapshot<M extends AnyStateMachine> = SnapshotFrom<M>
+export type AeonActor<M extends AnyStateMachine> = ActorRefFrom<M>
+
+/** Flatten nested state value for data-aeon-state attribute. */
+export function stateToAttr(value: unknown): string {
+  if (value == null || typeof value === 'string') return String(value ?? '')
+  return Object.entries(value as Record<string, unknown>)
+    .map(([k, v]) => `${k}:${stateToAttr(v)}`)
+    .join(' ')
+}

package/packages/core/src/philosophy.ts

@@ -0,0 +1,10 @@
+/**
+ * Aeon north star: behavior is defined as explicit state first; the interface must
+ * express the **totality** of that definition — every stable condition the model allows,
+ * and nothing the model does not allow.
+ */
+export const AEON_PRINCIPLE =
+  'State is defined first. UI represents the totality of that definition.' as const
+
+/** Shorthand used in docs and APIs. */
+export const UI_IS_FUNCTION_OF_STATE = 'UI = f(state)' as const