aeon-ui-engine 1.0.1 → 1.0.3

package/docs/ARCHITECTURE.md

@@ -1,125 +0,0 @@
-# Architecture
-
-Monorepo for **Aeon UI** — statechart-first headless components with Panda CSS styling.
-
----
-
-## Workspace layout
-
-```
-aeon-ui/
-├── AGENTS.md              # LLM entry (read first)
-├── docs/                  # Agent-oriented deep docs
-├── apps/demo/             # @aeon-ui/demo — site + playgrounds
-├── packages/
-│   ├── core/              # Anatomy, attrs, scroll snapshot, philosophy
-│   ├── primitives/        # XState machines (no DOM)
-│   ├── react/             # Headless React compounds
-│   ├── panda/             # Tokens, recipes, codegen (private)
-│   ├── ui/                # Styled layer
-│   ├── vue|solid|svelte/  # Adapter v0.1 (Switch)
-│   ├── signal|geometry|surface|scene|react-scene/  # Scene plane
-│   └── site/              # OG meta helpers
-├── pnpm-workspace.yaml
-└── package.json           # codegen, build, dev scripts
-```
-
----
-
-## Control plane vs scene plane
-
-| Plane | Packages | Role |
-|-------|----------|------|
-| **Control** | core, primitives, react, panda, ui | Forms, overlays, async, buttons — **this doc focuses here** |
-| **Scene** | signal, geometry, surface, scene, react-scene | Audio/visual materials, 3D/CSS scene — see [SCENE.md](../SCENE.md) |
-
-Same `data-aeon-scope` pattern on scene; does not change control contracts.
-
----
-
-## Three layers (dependency direction)
-
-```
-┌─────────────────────────────────────────────────────────┐
-│  @aeon-ui/ui          styled compounds + cn(recipes)    │
-└───────────────────────────┬─────────────────────────────┘
-                            │ imports
-┌───────────────────────────▼─────────────────────────────┐
-│  @aeon-ui/react       snapshot → DOM, a11y, context     │
-└───────────────────────────┬─────────────────────────────┘
-                            │
-        ┌───────────────────┼───────────────────┐
-        ▼                   ▼                   ▼
-┌───────────────┐   ┌───────────────┐   ┌───────────────┐
-│ @aeon-ui/     │   │ @aeon-ui/     │   │ @aeon-ui/     │
-│ primitives    │   │ core          │   │ panda         │
-│ (XState)      │   │ (anatomy)     │   │ (CSS/recipes) │
-└───────────────┘   └───────────────┘   └───────────────┘
-```
-
-- **primitives** depends on XState only (machines).
-- **core** has no React/XState — shared DOM contract.
-- **react** depends on core + primitives.
-- **panda** scans `react`, `ui`, `apps/demo` for classes; generates `styled-system/`.
-- **ui** depends on react + panda recipes.
-
----
-
-## Data flow (one render cycle)
-
-1. User event → `send({ type: '...' })` or DOM handler (Select) or scroll listener (Scroll).
-2. Machine / snapshot updates (or prop change for Button `status`).
-3. `partAttrs(scope, part, { state })` → `data-aeon-*` on element.
-4. Panda recipe conditions match `data-aeon-state` → computed class names.
-5. Styled wrapper merges `cn(recipe(), className)`.
-
----
-
-## Build pipeline
-
-| Step | Command | Output |
-|------|---------|--------|
-| Panda codegen | `pnpm codegen` | `packages/panda/styled-system/`, theme CSS |
-| Package build | `pnpm build` | `dist/` per package (tsup ESM + `.d.ts`) |
-| Demo | `pnpm dev` | Vite dev server |
-
-**Rule:** Always run `pnpm codegen` before `pnpm build` if recipes/tokens changed (root `build` script does this).
-
-Libraries use **tsup** from each package's `src/index.ts`.  
-Primitives also builds `src/machines/*.ts` as subpath exports.
-
----
-
-## TypeScript
-
-- Base: `tsconfig.base.json`
-- **verbatimModuleSyntax** — use `.js` in import paths inside TS sources.
-- Project references per package — extend base in each `tsconfig.json`.
-
----
-
-## Public vs private packages
-
-| Package | npm publish | Notes |
-|---------|-------------|-------|
-| core, primitives, react, ui | Yes (Changesets) | |
-| vue, solid, svelte | Yes | v0.1 scope |
-| panda | **Private** | Consumed via ui CSS + workspace |
-| demo, site | Private | |
-
-See [PUBLISHING.md](../PUBLISHING.md).
-
----
-
-## Extension points
-
-| Need | Location |
-|------|----------|
-| New machine | `packages/primitives/src/machines/` |
-| New anatomy scope | `packages/core/src/anatomy.ts` |
-| New headless component | `packages/react/src/<name>/` |
-| New recipe | `packages/panda/src/recipes/` + register in `panda.config.ts` |
-| New styled export | `packages/ui/src/<name>.tsx` + `index.ts` |
-| App-level machine | Consumer app + `useAeonMachine` |
-
-Step-by-step: [COMPONENT_CHECKLIST.md](./COMPONENT_CHECKLIST.md).

package/docs/COMPONENT_CHECKLIST.md

@@ -1,103 +0,0 @@
-# Component checklist (agents)
-
-Complete **in order** when adding a new component or promoting Select-style `useState` to a machine.
-
-Copy this checklist into your PR description and check boxes.
-
----
-
-## 0. Design (before code)
-
-- [ ] List every **stable state** the UI must express (totality).
-- [ ] List **events** and transitions (diagram or bullet list).
-- [ ] Decide: **XState** vs **derived DOM state** (Scroll pattern) vs **controlled prop** (Button `status`).
-- [ ] Choose **scope** string (e.g. `'rating'`) — lowercase, stable forever.
-- [ ] List **anatomy parts** (compound API surface).
-
----
-
-## 1. Machine (`@aeon-ui/primitives`)
-
-Skip only for Scroll-style derived state or intentional prop-only Button pattern.
-
-- [ ] Create `packages/primitives/src/machines/<name>.ts`
-- [ ] Export from `packages/primitives/src/index.ts`
-- [ ] Export constants for state names if reused (like `ASYNC_LIFECYCLE_STATES`)
-- [ ] Document events in file header comment
-
----
-
-## 2. Anatomy (`@aeon-ui/core`)
-
-- [ ] Add `{name}Anatomy` in `packages/core/src/anatomy.ts`
-- [ ] Parts match compound components 1:1
-- [ ] Use `partAttrs` / `stateToAttr` in React — do not hand-roll attribute names
-
----
-
-## 3. Headless React (`@aeon-ui/react`)
-
-- [ ] Folder: `packages/react/src/<name>/index.tsx` (split files if large)
-- [ ] `Component.Root` owns machine or state; context for children
-- [ ] Throw clear error if parts used outside Root (match existing components)
-- [ ] `mergeProps(partAttrs(...), consumerProps)` on interactive nodes
-- [ ] ARIA roles/attributes per [ACCESSIBILITY.md](../ACCESSIBILITY.md)
-- [ ] Export from `packages/react/src/index.ts`
-
----
-
-## 4. Panda (`@aeon-ui/panda`)
-
-- [ ] Recipe: `packages/panda/src/recipes/<name>.ts`
-- [ ] Slot names = anatomy part keys
-- [ ] Style via `data-aeon-state` / extended conditions in `panda.config.ts`
-- [ ] Register in `packages/panda/src/recipes/index.ts` and `panda.config.ts`
-- [ ] Run `pnpm codegen`
-
----
-
-## 5. Styled UI (`@aeon-ui/ui`)
-
-- [ ] File: `packages/ui/src/<name>.tsx`
-- [ ] Wrap headless parts with `cn(aeonName({ ... }), className)`
-- [ ] Export compound: `export const Name = { Root, ... }`
-- [ ] Export from `packages/ui/src/index.ts`
-
----
-
-## 6. Demo (`apps/demo`)
-
-- [ ] Playground section showing **all stable states** (rail/readout pattern when applicable)
-- [ ] Add to main `App.tsx` or existing section pattern
-- [ ] If machine-backed: add Mermaid to `apps/demo/src/aeonDiagrams.ts`
-
----
-
-## 7. Documentation
-
-- [ ] [COMPONENTS.md](../COMPONENTS.md) row
-- [ ] [docs/MACHINES.md](./MACHINES.md) row
-- [ ] [STATES.md](../STATES.md) section if new user-facing state concept
-- [ ] Package README if new public API surface
-
----
-
-## 8. Verify
-
-```bash
-pnpm codegen
-pnpm typecheck
-pnpm build
-```
-
-Manual: keyboard nav, focus visible, open/close, screen reader spot-check.
-
----
-
-## Anti-patterns (fail review)
-
-- Machine in primitives but `useState` for same concern in React
-- Missing `data-aeon-state` on styled surfaces
-- Recipe class names in product TSX instead of recipes
-- Demo shows only happy path (violates totality)
-- Orthogonal concerns merged into one boolean prop

package/docs/FILE_MAP.md

@@ -1,122 +0,0 @@
-# File map
-
-Quick path lookup for agents. Paths relative to repo root `/Users/brandoncryderman/AeonUI/`.
-
----
-
-## Entry points
-
-| File | Role |
-|------|------|
-| `AGENTS.md` | Agent instructions |
-| `package.json` | `codegen`, `build`, `dev` |
-| `pnpm-workspace.yaml` | `packages/*`, `apps/*` |
-| `apps/demo/src/main.tsx` | Demo bootstrap |
-| `apps/demo/src/App.tsx` | Demo sections |
-
----
-
-## `@aeon-ui/core`
-
-| File | Exports / role |
-|------|----------------|
-| `packages/core/src/index.ts` | Public API |
-| `packages/core/src/philosophy.ts` | `UI_IS_FUNCTION_OF_STATE`, `AEON_PRINCIPLE` |
-| `packages/core/src/anatomy.ts` | All `*Anatomy` |
-| `packages/core/src/attrs.ts` | `partAttrs`, `scopeAttrs`, `stateToAttr` |
-| `packages/core/src/machine.ts` | `createAeonMachine` (XState setup re-export) |
-| `packages/core/src/scroll.ts` | `getScrollSnapshot` |
-| `packages/core/src/types.ts` | Shared types |
-
----
-
-## `@aeon-ui/primitives`
-
-| File | Role |
-|------|------|
-| `packages/primitives/src/index.ts` | Machine exports |
-| `packages/primitives/src/machines/async.ts` | Async lifecycle |
-| `packages/primitives/src/machines/button.ts` | Button lifecycle |
-| `packages/primitives/src/machines/field.ts` | Parallel field regions |
-| `packages/primitives/src/machines/dialog.ts` | Modal open/closed |
-| `packages/primitives/src/machines/toggle.ts` | Switch, checkbox |
-| `packages/primitives/src/machines/tabs.ts` | Tabs |
-| `packages/primitives/src/machines/accordion.ts` | Accordion |
-| `packages/primitives/src/machines/popover.ts` | Menu, popover |
-| `packages/primitives/src/machines/toast.ts` | Toast item |
-
----
-
-## `@aeon-ui/react`
-
-| Directory | Component |
-|-----------|-----------|
-| `packages/react/src/async/` | Async (context, track, readout, actions) |
-| `packages/react/src/button/` | Button (prop `status`) |
-| `packages/react/src/field/` | Field |
-| `packages/react/src/scroll/` | Scroll + `use-scroll-state.ts` |
-| `packages/react/src/dialog/` | Dialog |
-| `packages/react/src/switch/` | Switch |
-| `packages/react/src/checkbox/` | Checkbox |
-| `packages/react/src/tabs/` | Tabs |
-| `packages/react/src/accordion/` | Accordion |
-| `packages/react/src/select/` | Select (useState) |
-| `packages/react/src/combobox/` | Combobox (useState) |
-| `packages/react/src/menu/` | Menu |
-| `packages/react/src/popover/` | Popover |
-| `packages/react/src/tooltip/` | Tooltip (useState) |
-| `packages/react/src/toast/` | Toast provider + items |
-| `packages/react/src/hooks/use-aeon-machine.ts` | `useAeonMachine` |
-| `packages/react/src/utils/merge-props.ts` | Prop merge helper |
-
----
-
-## `@aeon-ui/panda`
-
-| File | Role |
-|------|------|
-| `packages/panda/panda.config.ts` | Recipes, conditions, include paths |
-| `packages/panda/src/recipes/index.ts` | Recipe barrel |
-| `packages/panda/src/recipes/*.ts` | Per-component recipes |
-| `packages/panda/src/theme/themes.config.ts` | Mood palettes |
-| `packages/panda/styled-system/` | **Generated** — do not hand-edit |
-| `packages/panda/styles.css` | Base CSS entry |
-| `packages/panda/theme-runtime.css` | Generated theme vars |
-
----
-
-## `@aeon-ui/ui`
-
-| File | Styled wrapper |
-|------|----------------|
-| `packages/ui/src/button.tsx` | Button |
-| `packages/ui/src/async.tsx` | Async |
-| `packages/ui/src/field.tsx` | Field |
-| `packages/ui/src/scroll.tsx` | Scroll |
-| `packages/ui/src/dialog.tsx` | Dialog |
-| … | One file per component |
-| `packages/ui/src/index.ts` | Public exports |
-| `packages/ui/src/cn.ts` | Class merge |
-
----
-
-## Diagrams & docs
-
-| File | Role |
-|------|------|
-| `apps/demo/src/aeonDiagrams.ts` | Mermaid sources |
-| `apps/demo/src/components/DiagramsSection.tsx` | Diagrams UI |
-| `STATES.md` | State catalog |
-| `docs/MACHINES.md` | Machine truth table |
-
----
-
-## Framework adapters
-
-| Package | Reference impl |
-|---------|----------------|
-| `packages/vue/src/` | Switch |
-| `packages/solid/src/` | Switch |
-| `packages/svelte/src/` | Switch |
-
-Porting guide: [FRAMEWORKS.md](../FRAMEWORKS.md).

package/docs/GLOSSARY.md

@@ -1,125 +0,0 @@
-# Glossary
-
-Terms used across Aeon docs and code. Definitions are normative for this repo.
-
----
-
-## Aeon principle / north star
-
-**State is defined first. UI represents the totality of that definition.**  
-Short form: **UI = f(state)** where `state` is an explicit snapshot (usually from a statechart).
-
----
-
-## Anatomy
-
-Named **parts** of a compound component under a **scope**. Defined in `packages/core/src/anatomy.ts` via `anatomy(scope, parts)`.  
-Example: `asyncAnatomy` → `root`, `track`, `readout`, …
-
----
-
-## Scope
-
-Value of `data-aeon-scope` — component family (`button`, `async`, `field`). Must match anatomy `scope` string.
-
----
-
-## Part
-
-Value of `data-aeon-part` — which sub-node of the compound (`root`, `trigger`, `content`). Must match anatomy part key.
-
----
-
-## Snapshot
-
-Current value of an XState machine (and context). React headless reads `snapshot` from `useAeonMachine`.
-
----
-
-## Totality
-
-UI pattern where **every stable state** in the model is represented in the interface (e.g. five `Async.Track` segments for five async states). Opposite of showing only loading/success.
-
----
-
-## Headless layer
-
-`@aeon-ui/react` — behavior + DOM contract, no default Panda classes.
-
----
-
-## Styled layer
-
-`@aeon-ui/ui` — headless + `aeon*` Panda recipes applied via `cn()`.
-
----
-
-## Slot recipe
-
-Panda `defineSlotRecipe` — one style function per anatomy part (`aeonAsync().track`, …).
-
----
-
-## `partAttrs`
-
-Helper in `@aeon-ui/core` that sets `data-aeon-scope`, `data-aeon-part`, `data-aeon-state`, optional `data-disabled` / `data-focus`.
-
----
-
-## `stateToAttr`
-
-Flattens nested or parallel machine values into one `data-aeon-state` string (e.g. field regions).
-
----
-
-## Orthogonal regions
-
-Independent statechart regions inside one machine (field: interaction × validation × submission). Nguyen / Harel statecharts.
-
----
-
-## Lifecycle (async)
-
-States: `idle`, `loading`, `success`, `failure`, `empty` — plus optional `stale` on success.
-
----
-
-## Lifecycle (button)
-
-States: `idle`, `pending`, `success`, `failure`, `disabled` — exposed as Button `status` prop.
-
----
-
-## `useAeonMachine`
-
-Thin wrapper over `@xstate/react` `useMachine` — standard hook for primitives machines in React.
-
----
-
-## Scene plane
-
-Optional packages for visual/audio scenes (`@aeon-ui/scene`, …) — separate from form/control primitives.
-
----
-
-## Codegen
-
-`pnpm codegen` → Panda extracts classes and emits `styled-system/` and theme CSS. Required after recipe edits.
-
----
-
-## Layout mode
-
-`compact` or `wide` — which `ResponsiveLayoutSpec.modes` entry is active (usually from a max-width media query).
-
----
-
-## Layout composition
-
-`split`, `stack`, or `overlay` — how regions share the mat on screen. Mapped to CSS grid; pointer math uses measured rects + norm coords, not grid percentages.
-
----
-
-## Normalized plane (norm coords)
-
-0–100 coordinate system inside a region `DOMRect`. Stable across breakpoints when the region is measured after layout. See [LAYOUT_COORDINATES.md](./LAYOUT_COORDINATES.md).

package/docs/INDEX.md

@@ -1,53 +0,0 @@
-# Aeon UI documentation index
-
-Use this map to pick the right doc. **Agents should start at [AGENTS.md](../AGENTS.md).**
-
-## For coding agents (LLMs)
-
-| Document | Use when |
-|----------|----------|
-| [AGENTS.md](../AGENTS.md) | **Start here** — rules, workflows, naming |
-| [MACHINES.md](./MACHINES.md) | Machine vs prop vs `useState`; events |
-| [ARCHITECTURE.md](./ARCHITECTURE.md) | Monorepo layout, layers, dependencies |
-| [COMPONENT_CHECKLIST.md](./COMPONENT_CHECKLIST.md) | Add or change a component (ordered steps) |
-| [FILE_MAP.md](./FILE_MAP.md) | Where to find every artifact |
-| [GLOSSARY.md](./GLOSSARY.md) | Terms (anatomy, snapshot, totality, …) |
-| [LAYOUT_COORDINATES.md](./LAYOUT_COORDINATES.md) | Normalized plane, split/stack/overlay, game layouts |
-| [API_PATTERNS.md](./API_PATTERNS.md) | Copy-paste snippets by layer |
-
-## Philosophy & contracts
-
-| Document | Use when |
-|----------|----------|
-| [PHILOSOPHY.md](../PHILOSOPHY.md) | Why statecharts; north star |
-| [STATES.md](../STATES.md) | `data-aeon-*`; async, button, field, scroll |
-| [COMPONENTS.md](../COMPONENTS.md) | What ships vs planned |
-
-## Integration & shipping
-
-| Document | Use when |
-|----------|----------|
-| [INTEGRATION.md](../INTEGRATION.md) | Headless vs Panda vs `@aeon-ui/ui` |
-| [MIGRATION_FROM_ARK.md](./MIGRATION_FROM_ARK.md) | Replace `@ark-ui/react` with `@aeon-ui/react` (Vite, Next.js) |
-| [VITE_CONSUMER.md](./VITE_CONSUMER.md) | Vite aliases + local clone |
-| [FRAMEWORKS.md](../FRAMEWORKS.md) | Vue / Solid / Svelte adapters |
-| [ACCESSIBILITY.md](../ACCESSIBILITY.md) | Roles, focus, keyboard |
-| [PUBLISHING.md](../PUBLISHING.md) | Changesets, npm release |
-| [SCENE.md](../SCENE.md) | Scene plane (signal, geometry, surface) |
-
-## Package READMEs
-
-| Package | README |
-|---------|--------|
-| `@aeon-ui/core` | [packages/core/README.md](../packages/core/README.md) |
-| `@aeon-ui/primitives` | [packages/primitives/README.md](../packages/primitives/README.md) |
-| `@aeon-ui/react` | [packages/react/README.md](../packages/react/README.md) |
-| `@aeon-ui/panda` | [packages/panda/README.md](../packages/panda/README.md) |
-| `@aeon-ui/ui` | [packages/ui/README.md](../packages/ui/README.md) |
-| Scene / adapters | `packages/signal`, `geometry`, `surface`, `scene`, `react-scene`, `vue`, `solid`, `svelte` |
-
-## Live reference
-
-- Demo app: `apps/demo` — run `pnpm dev`
-- Diagrams: `apps/demo/src/aeonDiagrams.ts` (Mermaid ↔ machines)
-- Ground truth config: `packages/panda/panda.config.ts`