aeon-ui-engine 1.0.2 → 1.1.0

package/docs/LAYOUT_COORDINATES.md

@@ -1,178 +0,0 @@
-# Layout coordinates (responsive play surfaces)
-
-**Problem:** Games and rich apps need the same **logical** interaction space on desktop (split columns) and mobile (stacked lanes or overlays). CSS alone does not give you stable pointer math when regions move.
-
-**Aeon answer:** Separate three concerns — same pattern as `UI = f(state)`:
-
-| Layer | Owns | Package |
-|-------|------|---------|
-| **Behavior** | Statecharts, rounds, bets | `@aeon-ui/primitives` + app |
-| **Composition** | *Where* regions sit (split / stack / overlay) | CSS + `ResponsiveLayoutSpec` |
-| **Coordinates** | *Where* the user points inside a region | `@aeon-ui/core` `layout` module |
-
-Pointer logic uses a **normalized plane** (0–100 per axis) inside a measured `DOMRect`, not raw pixels.
-
----
-
-## North star
-
-**Layout mode is explicit. Coordinates are normalized. CSS projects mode to pixels.**
-
-- `data-aeon-layout-mode="compact" | "wide"`
-- `data-aeon-layout-composition="split" | "stack" | "overlay"`
-- Anatomy: `playSurfaceAnatomy` → `mat`, `table`, `dice`, `bank`
-
-Agents: [AGENTS.md](../AGENTS.md) · API: `packages/core/src/layout.ts`
-
----
-
-## Normalized plane
-
-```ts
-import {
-  normFromClient,
-  clientFromNorm,
-  clampNorm,
-  NORM_PLANE,
-} from '@aeon-ui/core'
-
-const rect = bowlEl.getBoundingClientRect()
-const aim = normFromClient(rect, e.clientX, e.clientY, {
-  origin: NORM_PLANE.bottomLeft, // y up — throws, dice
-  bounds: { xMin: 10, xMax: 90, yMin: 26, yMax: 74 },
-})
-```
-
-| Origin | Y direction | Use |
-|--------|-------------|-----|
-| `bottom-left` | Up | Dice throw, spatial games, scene aim |
-| `top-left` | Down | HUD-aligned hit targets (optional) |
-
-**Rule:** Pick one origin per region and keep it in the spec. Do not mix origins in one gesture pipeline.
-
----
-
-## Responsive layout spec
-
-Declare **composition per mode**, not ad hoc media queries in TS:
-
-```ts
-import type { ResponsiveLayoutSpec } from '@aeon-ui/core'
-
-export const ceeLoPlayLayout: ResponsiveLayoutSpec = {
-  compactMq: '(max-width: 39.99rem)',
-  modes: {
-    wide: {
-      id: 'ceelo-wide',
-      composition: 'split',
-      regions: [
-        { region: 'dice', slot: 'bowl', zIndex: 1 },
-        { region: 'table', slot: 'felt', zIndex: 1 },
-      ],
-      bounds: {
-        dice: { xMin: 8, xMax: 40, yMin: 8, yMax: 92 },
-        table: { xMin: 0, xMax: 100, yMin: 0, yMax: 100 },
-      },
-    },
-    compact: {
-      id: 'ceelo-compact',
-      composition: 'stack',
-      regions: [
-        { region: 'table', slot: 'felt', zIndex: 2 },
-        { region: 'dice', slot: 'dice', zIndex: 4 },
-      ],
-      bounds: {
-        dice: { xMin: 10, xMax: 90, yMin: 26, yMax: 74 },
-      },
-    },
-  },
-}
-```
-
-| Composition | Meaning | CSS strategy |
-|-------------|---------|--------------|
-| `split` | Regions side by side | `grid-template-columns: col + 1fr` |
-| `stack` | Regions in rows | `grid-template-rows: auto + lane` |
-| `overlay` | Same cell, z-index | Single `mat` area + absolute children |
-
-**Do not** encode `overlay` until stack/split is stable — Casino-games reverted overlay for this reason.
-
----
-
-## React
-
-```ts
-import { useLayoutMode } from '@aeon-ui/react'
-import { layoutModeAttrs, regionBoundsForMode } from '@aeon-ui/core'
-
-const { mode, composition } = useLayoutMode(ceeLoPlayLayout)
-const diceBounds = regionBoundsForMode(ceeLoPlayLayout, mode, 'dice')
-
-<div
-  data-aeon-scope="play"
-  data-aeon-part="mat"
-  {...layoutModeAttrs(mode, composition.composition)}
->
-```
-
-Measure the **dice region** element for `normFromClient`, not the full mat, when bounds are defined per region.
-
-```ts
-import { measureElement, resolveRegionRect, normFromClient } from '@aeon-ui/core'
-
-const diceRect = resolveRegionRect(
-  measureElement(bowlRef.current),
-  measureElement(matRef.current),
-)
-```
-
----
-
-## CSS contract
-
-1. Map `composition.regions[].slot` → `grid-template-areas` per `data-aeon-layout-mode`.
-2. Never drive throw math from `grid-template-columns` percentages — measure DOM.
-3. Optional Panda conditions:
-
-```css
-[data-aeon-scope='play'][data-aeon-layout-mode='compact'][data-aeon-layout-composition='stack'] {
-  /* stack rules */
-}
-```
-
----
-
-## Checklist (new game surface)
-
-- [ ] List logical regions (`table`, `dice`, `bank`, …).
-- [ ] Add `ResponsiveLayoutSpec` with `wide` + `compact` compositions.
-- [ ] Add per-mode `bounds` for any region that receives drag/aim.
-- [ ] CSS: two layouts keyed on `data-aeon-layout-mode` (no overlay until tested).
-- [ ] TS: `useLayoutMode` + `normFromClient` on measured region rects.
-- [ ] Demo or story: resize across breakpoint; aim stays inside bounds.
-
----
-
-## Relation to scene plane
-
-| Package | Role |
-|---------|------|
-| `@aeon-ui/core` `layout` | App/play surface, pointer norm, breakpoints |
-| `@aeon-ui/geometry` | Decorative scene grids, SVG, `sceneAttrs` |
-| `@aeon-ui/scene` | CSS 3D presentation |
-
-Scene coordinates are visual; **layout coordinates** are for input and game logic.
-
----
-
-## Reference implementation
-
-[Casino-games](https://github.com/GenericCPU/Casino-games) `shared/game/dicePlayLayout.ts` and `diceAim.ts` already use this model informally (`AimBounds` = `NormRect`). Migrating to `@aeon-ui/core` keeps one API across products.
-
----
-
-## See also
-
-- [STATES.md](../STATES.md) — scroll snapshot (derived spatial state, same idea)
-- [docs/ARCHITECTURE.md](./ARCHITECTURE.md)
-- [packages/core/README.md](../packages/core/README.md)

package/docs/MACHINES.md

@@ -1,171 +0,0 @@
-# Machines truth table
-
-**Purpose:** Prevent agents from wiring the wrong state layer. This table reflects **current implementation**, not aspirational catalog rows.
-
----
-
-## Summary table
-
-| Component | `@aeon-ui/primitives` machine | Headless runtime | `data-aeon-state` source |
-|-----------|------------------------------|------------------|--------------------------|
-| **Async** | `createAsyncMachine()` | `useAeonMachine` in `Async` context | Snapshot value (+ `stale` flag on readout) |
-| **Field** | `fieldMachine` (parallel) | `useAeonMachine` | `stateToAttr(snapshot.value)` |
-| **Button** | `buttonLifecycleMachine` | **`status` prop** on `Button.Root` | Prop string, not machine by default |
-| **Switch** | `toggleMachine` | `useAeonMachine` | Snapshot |
-| **Checkbox** | `toggleMachine` | `useAeonMachine` | Snapshot |
-| **Dialog** | `dialogMachine` | `useAeonMachine` | `open` / `closed` |
-| **Tabs** | `tabsMachine` | `useAeonMachine` | Selected tab value |
-| **Accordion** | `accordionMachine` | `useAeonMachine` | Per-item open |
-| **Menu** | `popoverMachine` | `useAeonMachine` | `open` / `closed` |
-| **Popover** | `popoverMachine` | `useAeonMachine` | `open` / `closed` |
-| **Toast** (item) | `toastMachine` | `useAeonMachine` | visible / hidden |
-| **Select** | `popoverMachine` | `useAeonMachine` | `open` / `closed`; highlight in React |
-| **Combobox** | — | **`useState`** (open, query, highlight) | `open` / `closed` + highlight attrs |
-| **Tooltip** | — | **`useState(open)`** | `open` / `closed`; touch tap toggle |
-| **Scroll** | — | **`getScrollSnapshot()`** | Derived overflow/edge tokens |
-| **Separator** | — | **static orientation prop** | horizontal / vertical |
-| **Progress** | — | **props** (`value`, `indeterminate`) | idle / loading / complete |
-| **RadioGroup** | `tabsMachine` | `useAeonMachine` | selected value |
-| **Slider** | `sliderMachine` | `useAeonMachine` | idle / dragging + numeric value |
-| **PinInput** | — | **`useState`** | idle / complete |
-
----
-
-## Button: prop vs machine (critical)
-
-Two valid patterns — **do not conflate them**:
-
-### Pattern A — Headless / styled (default)
-
-```tsx
-<Button.Root status="pending" aria-busy>
-  Saving…
-</Button.Root>
-```
-
-- File: `packages/react/src/button/index.tsx`
-- `status` ∈ `idle` | `pending` | `success` | `failure` | `disabled`
-- Sets `data-aeon-state` via `partAttrs`
-- **No** `useAeonMachine` inside Button
-
-### Pattern B — Chart-driven (app / demo)
-
-```tsx
-const [snapshot, send] = useAeonMachine(buttonLifecycleMachine)
-const status = snapshot.value as ButtonStatus
-<Button.Root status={status} onClick={() => send({ type: 'PRESS' })} />
-```
-
-- Machine: `packages/primitives/src/machines/button.ts`
-- Demo: playground **Button lifecycle**
-
----
-
-## Async events
-
-Machine: `packages/primitives/src/machines/async.ts`  
-Factory: `createAsyncMachine<T>()` — use per-region instance in context.
-
-| Event | Effect |
-|-------|--------|
-| `FETCH` | → `loading` |
-| `RESOLVE` `{ data }` | → `success` or `empty` if `isEmptyAsyncData(data)` |
-| `REJECT` `{ error }` | → `failure` |
-| `RESET` | → `idle`, clear context |
-| `STALE` | Context flag while staying in `success` |
-| `REFRESH` | Re-fetch from success/empty/failure |
-
-Constants: `ASYNC_LIFECYCLE_STATES`, `isEmptyAsyncData()`.
-
-React: `Async.Root` provides context; children call `send` via `useAsyncContext()`.
-
----
-
-## Field events (orthogonal)
-
-Machine: `packages/primitives/src/machines/field.ts` — **parallel** regions.
-
-| Region | States |
-|--------|--------|
-| `interaction` | `pristine` · `dirty` |
-| `validation` | `valid` · `invalid` |
-| `submission` | `idle` · `pending` |
-
-| Event | Typical use |
-|-------|-------------|
-| `INPUT` | User typed |
-| `BLUR` | Left control |
-| `VALIDATE` `{ valid: boolean }` | After rule run |
-| `SUBMIT` | Form submit started |
-| `SUBMIT_DONE` / `SUBMIT_FAIL` | End pending |
-| `RESET` | Clear field |
-
-Flatten for DOM:
-
-```ts
-import { stateToAttr } from '@aeon-ui/core'
-stateToAttr(snapshot.value) // "interaction:dirty validation:invalid submission:idle"
-```
-
----
-
-## Button lifecycle events
-
-Machine: `buttonLifecycleMachine` in `packages/primitives/src/machines/button.ts`
-
-| Event | From → To (simplified) |
-|-------|------------------------|
-| `PRESS` | idle → pending |
-| `SUCCEED` | pending → success |
-| `FAIL` | pending → failure |
-| `DISABLE` / `ENABLE` | ↔ disabled |
-| `RESET` | → idle |
-
----
-
-## Dialog / toggle / tabs / accordion
-
-| Machine | File | Notes |
-|---------|------|-------|
-| `dialogMachine` | `machines/dialog.ts` | open/closed; Escape handled in React |
-| `toggleMachine` | `machines/toggle.ts` | Switch + Checkbox |
-| `tabsMachine` | `machines/tabs.ts` | Single active value |
-| `accordionMachine` | `machines/accordion.ts` | Multiple items |
-| `popoverMachine` | `machines/popover.ts` | Menu, Popover, Select |
-| `toastMachine` | `machines/toast.ts` | Auto-dismiss input |
-
-Inspect each file for full transition tables. Diagrams: `apps/demo/src/aeonDiagrams.ts`.
-
----
-
-## Combobox / Tooltip
-
-**No primitives machine.** Open/query/highlight live in:
-
-- `packages/react/src/combobox/index.tsx` (item registry for filtering)
-- `packages/react/src/tooltip/index.tsx`
-
-**Select** reuses `popoverMachine` for open/closed; option order comes from DOM (`role="option"` ids), not a registry.
-
----
-
-## Scroll
-
-```ts
-import { getScrollSnapshot } from '@aeon-ui/core'
-```
-
-Hook: `packages/react/src/scroll/use-scroll-state.ts` — listens to scroll/resize on viewport.
-
-States: `idle`, `overflow-y`, `overflow-x`, `overflow-both`, `at-start-y`, `between-y`, `at-end-y`, … (see [STATES.md](../STATES.md) §5).
-
----
-
-## Diagram sync
-
-When you change transitions in `packages/primitives/src/machines/`:
-
-1. Update matching diagram string in `apps/demo/src/aeonDiagrams.ts`
-2. Mention in PR / commit that diagrams were synced
-
-No automated test enforces sync yet — **manual discipline required**.

package/docs/MIGRATION_FROM_ARK.md

@@ -1,295 +0,0 @@
-# Migrating from Ark UI to Aeon UI
-
-Step-by-step guide for apps that use **`@ark-ui/react`** headless primitives with your own CSS (Tailwind, CSS modules, etc.). Chakra-wrapped Ark recipes are out of scope here—migrate the headless boundary first, then revisit styling.
-
-**Reference consumers**
-
-| App | Stack | Notes |
-|-----|-------|--------|
-| [spidercorp.xyz](https://github.com/GenericCPU/spydercorp.xyz) | Vite + React | Field, Select, Dialog, Toast |
-| [soundbase.click](https://github.com/GenericCPU/soundbase) | Next.js + React | Avatar (Chakra remains for other widgets) |
-
----
-
-## 1. Inventory Ark usage
-
-```bash
-rg "@ark-ui" --glob '*.{ts,tsx}' .
-```
-
-Group imports by component (`dialog`, `select`, `field`, `avatar`, `toast`, `portal`, `collection`, …). Migrate in this order when possible:
-
-1. **Leaf primitives** with a direct Aeon equivalent (Avatar, Switch, Checkbox).
-2. **Forms** — Field, Select, Combobox.
-3. **Overlays** — Dialog, Menu, Popover, Tooltip.
-4. **Toasts** — replace `createToaster` with `Toast.Provider` + `useToast()`.
-
-Components with **no** Aeon headless yet (Slider, Number Input, Steps, …): keep Ark for that file until Aeon ships them, or replace with a minimal local implementation.
-
----
-
-## 2. Install Aeon runtime deps
-
-Aeon headless peers:
-
-```bash
-npm install @xstate/react xstate
-```
-
-When `@aeon-ui/*` is on npm:
-
-```bash
-npm install @aeon-ui/react @aeon-ui/core @aeon-ui/primitives
-```
-
-Until publish, point the bundler at a built clone (sections 3–4).
-
----
-
-## 3. Build Aeon once
-
-From the Aeon UI repo:
-
-```bash
-pnpm run build:headless
-```
-
-In the consumer `package.json`:
-
-```json
-{
-  "scripts": {
-    "aeon:ensure": "node <path-to-AeonUI>/scripts/ensure-headless-built.mjs",
-    "prebuild": "npm run aeon:ensure"
-  }
-}
-```
-
-CI: set `AEON_UI_ROOT` to the checkout path.
-
----
-
-## 4. Wire the bundler
-
-### Vite
-
-See [VITE_CONSUMER.md](./VITE_CONSUMER.md) for full `resolve.alias`, `optimizeDeps.include`, and TypeScript `paths`.
-
-### Next.js (recommended: `file:` links)
-
-Turbopack often **cannot** import files outside the app root via `resolveAlias`. Link the built packages into `node_modules` instead:
-
-```json
-{
-  "dependencies": {
-    "@aeon-ui/core": "file:../../../AeonUI/packages/core",
-    "@aeon-ui/primitives": "file:../../../AeonUI/packages/primitives",
-    "@aeon-ui/react": "file:../../../AeonUI/packages/react",
-    "@xstate/react": "^5.0.3",
-    "xstate": "^5.19.2"
-  }
-}
-```
-
-Run `npm install` after `pnpm run build:headless` in Aeon UI (or `npm run aeon:ensure` in the consumer).
-
-`next.config.mjs`:
-
-```js
-export default {
-  transpilePackages: ['@aeon-ui/react', '@aeon-ui/core', '@aeon-ui/primitives'],
-}
-```
-
-Optional: `next build --webpack` if you hit Turbopack edge cases.
-
-`tsconfig.json` paths (optional; `file:` installs usually typecheck via package `types`):
-
-```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"]
-    }
-  }
-}
-```
-
-Mark client boundaries: `'use client'` on files that import `@aeon-ui/react`.
-
----
-
-## 5. API mapping (Ark → Aeon)
-
-| Ark | Aeon |
-|-----|------|
-| `data-scope` / `data-part` | `data-aeon-scope` / `data-aeon-part` |
-| `data-state` | `data-aeon-state` |
-| `Field.Input` | `Field.Control` |
-| `Field.Textarea` | `Field.Textarea` |
-| `createListCollection` + `Select.*` | `Select.Root` → `Trigger` + `ValueText` → `Positioner` → `Content` → `Item` |
-| `Portal` + `Dialog.*` | `Dialog.Portal` wraps `Backdrop`, `Positioner`, `Content` |
-| `Avatar.Root` / `Image` / `Fallback` | Same part names under `@aeon-ui/react` |
-| `createToaster` + `Toaster` | `Toast.Provider`, `Toast.Viewport`, `useToast().publish()` |
-
-### Select (required structure)
-
-```tsx
-import { Select } from '@aeon-ui/react'
-
-<Select.Root value={value} onValueChange={setValue}>
-  <Select.Trigger>
-    <Select.ValueText>{label}</Select.ValueText>
-  </Select.Trigger>
-  <Select.Positioner>
-    <Select.Content>
-      <Select.Item value="a">Option A</Select.Item>
-    </Select.Content>
-  </Select.Positioner>
-</Select.Root>
-```
-
-Use `portalled={false}` in tests or fixed-height containers.
-
-### Dialog
-
-```tsx
-<Dialog.Root open={open} onOpenChange={setOpen}>
-  <Dialog.Trigger>Open</Dialog.Trigger>
-  <Dialog.Portal>
-    <Dialog.Backdrop />
-    <Dialog.Positioner>
-      <Dialog.Content>
-        <Dialog.Title>Title</Dialog.Title>
-        <Dialog.CloseTrigger>Close</Dialog.CloseTrigger>
-      </Dialog.Content>
-    </Dialog.Positioner>
-  </Dialog.Portal>
-</Dialog.Root>
-```
-
-### Avatar (shadcn-style wrapper)
-
-Keep your `components/ui/avatar.tsx` as a thin Tailwind wrapper over Aeon parts so call sites stay unchanged:
-
-```tsx
-import { Avatar as AeonAvatar } from '@aeon-ui/react'
-
-function Avatar({ className, ...props }) {
-  return <AeonAvatar.Root className={cn('relative flex size-8 ...', className)} {...props} />
-}
-```
-
-Aeon does not force width/height recipes—Tailwind `size-*` on `Root` works.
-
-### Toasts
-
-```tsx
-// layout.tsx
-import { Toast } from '@aeon-ui/react'
-
-<Toast.Provider>
-  {children}
-  <Toast.Viewport placement="bottom-end" />
-</Toast.Provider>
-
-// anywhere
-const { publish } = useToast()
-publish({ title: 'Saved' })
-```
-
----
-
-## 6. Restyle with `data-aeon-*`
-
-Ark CSS often targets `[data-part=trigger]`. Rename selectors:
-
-```css
-/* was: [data-scope='select'][data-part='content'] */
-[data-aeon-scope='select'][data-aeon-part='content'] {
-  /* ... */
-}
-```
-
-State:
-
-```css
-[data-aeon-scope='select'][data-aeon-part='item'][data-aeon-state='highlighted'] {
-  background: var(--accent);
-}
-```
-
-See [STATES.md](../STATES.md) and [INTEGRATION.md](../INTEGRATION.md).
-
----
-
-## 7. Remove Ark
-
-```bash
-npm uninstall @ark-ui/react
-```
-
-Re-run build and grep for stragglers:
-
-```bash
-rg "@ark-ui" .
-```
-
----
-
-## 8. Verify
-
-| Check | Command / action |
-|-------|------------------|
-| Aeon tests | `cd AeonUI && pnpm test:headless` |
-| Consumer build | `npm run build` / `vite build` |
-| Select | Open list, keyboard, pick option, Escape |
-| Dialog | Open, focus trap, Escape, scroll lock |
-| Avatar | Image load, fallback when missing/broken |
-| Toasts | `publish` after provider mount |
-
----
-
-## 9. Chakra + Ark stacks
-
-Many HandCash templates use **Chakra v3 recipes** built on Ark. Migrating “off Ark” does not require removing Chakra in one pass:
-
-1. Replace **direct** `@ark-ui/react` imports (e.g. `components/ui/avatar.tsx`).
-2. Later, swap Chakra widgets for `@aeon-ui/react` or `@aeon-ui/ui` per component.
-
-soundbase.click keeps Chakra for Button, Dialog, Select, etc.; only Avatar uses Aeon headless today.
-
----
-
-## Light / dark transitions (Tailwind + next-themes)
-
-Import Aeon’s transition stylesheet and bridge `data-aeon-mode` to your existing theme toggle:
-
-```css
-/* globals.css */
-@import '@aeon-ui/core/theme-transition.css';
-```
-
-```tsx
-import { AeonThemeBridge } from '@/components/aeon-theme-bridge' // syncs next-themes → data-aeon-mode
-import { runAeonThemeTransition } from '@aeon-ui/core'
-
-// layout: inside <ThemeProvider>
-<AeonThemeBridge />
-
-// theme menu
-runAeonThemeTransition(() => setTheme('dark'))
-```
-
-Reference: **soundbase.click** (`components/aeon-theme-bridge.tsx`).
-
----
-
-## Related docs
-
-- [VITE_CONSUMER.md](./VITE_CONSUMER.md) — Vite-specific aliases
-- [MACHINES.md](./MACHINES.md) — which components use XState
-- [ACCESSIBILITY.md](../ACCESSIBILITY.md) — roles and keyboard
-- [API_PATTERNS.md](./API_PATTERNS.md) — copy-paste snippets