aeon-ui-engine 1.0.1 → 1.0.3

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to **aeon-ui-engine** are documented here.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.3] - 2026-06-02
+
+### Added
+
+- `aeon-ui-engine/vite` export — `aeonUiViteAliases()` and `aeonUiOptimizeDeps()` for npm consumers.
+- **[CONSUMER.md](./CONSUMER.md)** — accurate install, Vite alias, and TypeScript path setup.
+
+### Changed
+
+- npm tarball excludes monorepo dev apps (`.npmignore`); ships `packages/`, `scripts/`, and consumer docs only.
+- Site hero and FAQ document peer deps plus required Vite wiring (not `import` alone after `npm install aeon-ui-engine`).
+
+## [1.0.2] - 2026-06-02
+
+### Added
+
+- Shared Panda tokens `controlMinHXs`, `controlMinHSm`, `controlMinHMd`, and `controlMinHLg` so compact control heights stay aligned across components.
+
+### Changed
+
+- Button, select trigger, and combobox input recipes reference the shared control-height tokens instead of hardcoded `rem` values.
+- Demo header toolbar uses `size="sm"` for buttons alongside the select (same compact tier) without page-level height overrides.
+
+## [1.0.1] - 2026-06-02
+
+### Changed
+
+- Open Graph preview image shows `npm install aeon-ui-engine` and is served at `/og-aeon-ui-engine.png` for cache-friendly social sharing.
+- Demo site copy standardized on the `aeon-ui-engine` npm package name.
+
+### Fixed
+
+- Mobile header theme preset select shows a visible **Theme** label instead of chevron-only.
+
+## [1.0.0] - 2026-06-02
+
+### Added
+
+- Initial npm release of **aeon-ui-engine** — monorepo bundle with headless statechart primitives, React bindings, Panda styled layer, and themes.
+
+[1.0.3]: https://github.com/GenericCPU/aeon-ui/compare/v1.0.2...v1.0.3
+[1.0.2]: https://github.com/GenericCPU/aeon-ui/compare/v1.0.1...v1.0.2
+[1.0.1]: https://github.com/GenericCPU/aeon-ui/compare/v1.0.0...v1.0.1
+[1.0.0]: https://github.com/GenericCPU/aeon-ui/releases/tag/v1.0.0

package/CONSUMER.md

@@ -0,0 +1,86 @@
+# Using `aeon-ui-engine` from npm
+
+The npm package **`aeon-ui-engine`** ships the full `@aeon-ui/*` workspace (source + prebuilt Panda CSS). Scoped packages like `@aeon-ui/react` are **not** separate npm installs — wire them through Vite (or your bundler) after installing the engine.
+
+## 1. Install
+
+```bash
+npm install aeon-ui-engine react react-dom xstate @xstate/react
+```
+
+Use the same peer versions your app already runs (`react` 18 or 19).
+
+## 2. Vite aliases (required)
+
+`@aeon-ui/*` imports resolve through aliases bundled with the engine:
+
+```ts
+// vite.config.ts
+import react from '@vitejs/plugin-react'
+import { defineConfig } from 'vite'
+import { aeonUiOptimizeDeps, aeonUiViteAliases } from 'aeon-ui-engine/vite'
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: aeonUiViteAliases(),
+  },
+  optimizeDeps: aeonUiOptimizeDeps(),
+})
+```
+
+Optional: point at a local monorepo checkout instead of npm (contributors):
+
+```ts
+aeonUiViteAliases({ packagesRoot: '/path/to/aeon-ui/packages' })
+// or set AEON_UI_ROOT=/path/to/aeon-ui
+```
+
+## 3. TypeScript paths
+
+Extend the engine base config and map scoped imports to the bundled packages:
+
+```json
+{
+  "extends": "../node_modules/aeon-ui-engine/tsconfig.base.json",
+  "compilerOptions": {
+    "paths": {
+      "@aeon-ui/core": ["../node_modules/aeon-ui-engine/packages/core/src/index.ts"],
+      "@aeon-ui/primitives": ["../node_modules/aeon-ui-engine/packages/primitives/src/index.ts"],
+      "@aeon-ui/react": ["../node_modules/aeon-ui-engine/packages/react/src/index.ts"],
+      "@aeon-ui/ui": ["../node_modules/aeon-ui-engine/packages/ui/src/index.ts"],
+      "@aeon-ui/surface": ["../node_modules/aeon-ui-engine/packages/surface/src/index.ts"],
+      "@aeon-ui/panda/styled-system/css": [
+        "../node_modules/aeon-ui-engine/packages/panda/styled-system/css/index.d.ts"
+      ],
+      "@aeon-ui/panda/styled-system/recipes": [
+        "../node_modules/aeon-ui-engine/packages/panda/styled-system/recipes/index.d.ts"
+      ]
+    }
+  }
+}
+```
+
+Adjust `../node_modules/…` if your app tsconfig lives deeper than one folder from the repo root.
+
+## 4. Import CSS once (styled layer)
+
+```tsx
+import '@aeon-ui/panda/styles.css'
+import '@aeon-ui/panda/theme-runtime.css'
+```
+
+Add `scrollbars.css` / `chrome.css` when you want the demo chrome. See [INTEGRATION.md](./INTEGRATION.md).
+
+## 5. Use components
+
+```tsx
+import { Button, Dialog } from '@aeon-ui/ui'
+import { useAeonMachine } from '@aeon-ui/react'
+```
+
+Headless-only apps can import from `@aeon-ui/react` and style with `data-aeon-*` selectors — see [docs/VITE_CONSUMER.md](./docs/VITE_CONSUMER.md).
+
+## Reference consumer
+
+The [Casino-games](https://github.com/GenericCPU/Casino-games) repo uses this exact pattern (`scripts/vite.casino.mjs`, root `aeon-ui-engine` dependency).

package/INTEGRATION.md

@@ -2,6 +2,8 @@
 
 **Agents:** [AGENTS.md](./AGENTS.md) · [docs/API_PATTERNS.md](./docs/API_PATTERNS.md)
 
+**npm consumers:** start with **[CONSUMER.md](./CONSUMER.md)** — install `aeon-ui-engine`, peer deps, and `aeonUiViteAliases()` before any `@aeon-ui/*` import works.
+
 Aeon UI is **three layers**. You can use one or all.
 
 ## 1. Headless only (`@aeon-ui/react`)

package/README.md

@@ -25,15 +25,26 @@ Aeon UI models interactive behavior as executable [statecharts](https://www.thes
 
 ## Quick start
 
-The monorepo is published on npm as **`aeon-ui-engine`**:
+The monorepo is published on npm as **`aeon-ui-engine`** (bundles all `@aeon-ui/*` workspace packages):
 
 ```bash
-npm install aeon-ui-engine
+npm install aeon-ui-engine react react-dom xstate @xstate/react
 ```
 
-Open [https://github.com/GenericCPU/aeon-ui](https://github.com/GenericCPU/aeon-ui) for the repo. The marketing demo lives at [https://aeon-ui.com](https://aeon-ui.com) — set `VITE_SITE_ORIGIN` to that origin in Vercel so Open Graph previews resolve the social image in `apps/demo/public/` correctly.
+**Important:** `@aeon-ui/react`, `@aeon-ui/ui`, etc. are **not** separate npm packages yet. After installing the engine, wire Vite so those imports resolve:
+
+```ts
+import { aeonUiOptimizeDeps, aeonUiViteAliases } from 'aeon-ui-engine/vite'
 
-After installing `aeon-ui-engine`, use the core, React, styled UI, and Panda layers included in the package.
+export default defineConfig({
+  resolve: { alias: aeonUiViteAliases() },
+  optimizeDeps: aeonUiOptimizeDeps(),
+})
+```
+
+Full copy-paste setup (TypeScript paths, CSS imports): **[CONSUMER.md](./CONSUMER.md)**.
+
+Open [https://github.com/GenericCPU/aeon-ui](https://github.com/GenericCPU/aeon-ui) for the repo. The marketing demo lives at [https://aeon-ui.com](https://aeon-ui.com) — set `VITE_SITE_ORIGIN` to that origin in Vercel so Open Graph previews resolve the social image in `apps/demo/public/` correctly.
 
 After changing recipes or tokens in `packages/panda`:
 

package/package.json

@@ -1,7 +1,23 @@
 {
   "name": "aeon-ui-engine",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "private": false,
+  "type": "module",
+  "exports": {
+    "./vite": "./scripts/vite-aliases.mjs",
+    "./tsconfig.base.json": "./tsconfig.base.json",
+    "./CONSUMER.md": "./CONSUMER.md"
+  },
+  "files": [
+    "packages",
+    "scripts",
+    "tsconfig.base.json",
+    "CONSUMER.md",
+    "INTEGRATION.md",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
   "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",

package/packages/core/dist/index.d.ts

@@ -0,0 +1,257 @@
+import { AnyStateMachine, ActorRefFrom, SnapshotFrom } from 'xstate';
+export { setup as createAeonMachine } from 'xstate';
+
+/**
+ * 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.
+ */
+declare const AEON_PRINCIPLE: "State is defined first. UI represents the totality of that definition.";
+/** Shorthand used in docs and APIs. */
+declare const UI_IS_FUNCTION_OF_STATE: "UI = f(state)";
+
+/** Part keys for compound components — scope + named parts for styling and docs. */
+declare function anatomy<const T extends readonly string[]>(scope: string, parts: T): Record<T[number], T[number]> & {
+    scope: typeof scope;
+};
+declare const buttonAnatomy: Record<"root" | "group" | "label" | "icon", "root" | "group" | "label" | "icon"> & {
+    scope: string;
+};
+declare const switchAnatomy: Record<"root" | "label" | "control" | "thumb" | "hiddenInput", "root" | "label" | "control" | "thumb" | "hiddenInput"> & {
+    scope: string;
+};
+declare const checkboxAnatomy: Record<"root" | "label" | "control" | "hiddenInput" | "indicator", "root" | "label" | "control" | "hiddenInput" | "indicator"> & {
+    scope: string;
+};
+declare const dialogAnatomy: Record<"root" | "trigger" | "portal" | "backdrop" | "positioner" | "content" | "title" | "description" | "closeTrigger", "root" | "trigger" | "portal" | "backdrop" | "positioner" | "content" | "title" | "description" | "closeTrigger"> & {
+    scope: string;
+};
+declare const tabsAnatomy: Record<"root" | "indicator" | "trigger" | "content" | "list", "root" | "indicator" | "trigger" | "content" | "list"> & {
+    scope: string;
+};
+declare const accordionAnatomy: Record<"root" | "item" | "itemTrigger" | "itemContent" | "itemIndicator", "root" | "item" | "itemTrigger" | "itemContent" | "itemIndicator"> & {
+    scope: string;
+};
+/** Async data region — track shows every lifecycle state; readout + actions mirror snapshot. */
+declare const asyncAnatomy: Record<"root" | "track" | "segment" | "readout" | "readoutRail" | "readoutBody" | "actions", "root" | "track" | "segment" | "readout" | "readoutRail" | "readoutBody" | "actions"> & {
+    scope: string;
+};
+/** Form field — orthogonal interaction × validation × submission (see STATES.md). */
+declare const fieldAnatomy: Record<"root" | "label" | "control" | "textarea" | "message" | "hint", "root" | "label" | "control" | "textarea" | "message" | "hint"> & {
+    scope: string;
+};
+/** Scroll viewport — overflow axis + edge position on data-aeon-state. */
+declare const scrollAnatomy: Record<"root" | "content" | "viewport", "root" | "content" | "viewport"> & {
+    scope: string;
+};
+/**
+ * Play / game surface — mat shell with table, dice, and bank regions.
+ * Use with normalized layout coords (@see docs/LAYOUT_COORDINATES.md).
+ */
+declare const playSurfaceAnatomy: Record<"mat" | "table" | "dice" | "bank", "mat" | "table" | "dice" | "bank"> & {
+    scope: string;
+};
+declare const selectAnatomy: Record<"root" | "icon" | "trigger" | "positioner" | "content" | "item" | "value", "root" | "icon" | "trigger" | "positioner" | "content" | "item" | "value"> & {
+    scope: string;
+};
+/** Typeahead listbox — extends select with filter input and empty state. */
+declare const comboboxAnatomy: Record<"root" | "icon" | "content" | "item" | "input" | "empty", "root" | "icon" | "content" | "item" | "input" | "empty"> & {
+    scope: string;
+};
+declare const popoverAnatomy: Record<"root" | "trigger" | "positioner" | "content" | "closeTrigger" | "arrow", "root" | "trigger" | "positioner" | "content" | "closeTrigger" | "arrow"> & {
+    scope: string;
+};
+declare const menuAnatomy: Record<"root" | "trigger" | "positioner" | "content" | "item" | "separator", "root" | "trigger" | "positioner" | "content" | "item" | "separator"> & {
+    scope: string;
+};
+declare const tooltipAnatomy: Record<"root" | "trigger" | "positioner" | "content" | "arrow", "root" | "trigger" | "positioner" | "content" | "arrow"> & {
+    scope: string;
+};
+declare const toastAnatomy: Record<"root" | "title" | "description" | "closeTrigger" | "viewport", "root" | "title" | "description" | "closeTrigger" | "viewport"> & {
+    scope: string;
+};
+/** Profile image — loaded / loading / error on root `data-aeon-state`. */
+declare const avatarAnatomy: Record<"root" | "image" | "fallback", "root" | "image" | "fallback"> & {
+    scope: string;
+};
+declare const separatorAnatomy: Record<"root", "root"> & {
+    scope: string;
+};
+/** Progress bar — idle / loading / complete on root `data-aeon-state`. */
+declare const progressAnatomy: Record<"root" | "label" | "track" | "range", "root" | "label" | "track" | "range"> & {
+    scope: string;
+};
+declare const radioGroupAnatomy: Record<"root" | "item" | "itemIndicator" | "itemControl" | "itemLabel", "root" | "item" | "itemIndicator" | "itemControl" | "itemLabel"> & {
+    scope: string;
+};
+declare const sliderAnatomy: Record<"root" | "thumb" | "track" | "range" | "valueText", "root" | "thumb" | "track" | "range" | "valueText"> & {
+    scope: string;
+};
+declare const pinInputAnatomy: Record<"root" | "input", "root" | "input"> & {
+    scope: string;
+};
+
+type AttrOptions = {
+    state?: string | string[];
+    disabled?: boolean;
+    focus?: boolean;
+    highlighted?: boolean;
+};
+/** Scope + part on the component root (e.g. accordion root). */
+declare function scopeAttrs(scope: string, part?: string, options?: AttrOptions): Record<string, unknown>;
+/** Part only — use on children inside a scoped root. */
+declare function partOnlyAttrs(part: string, options?: AttrOptions): Record<string, unknown>;
+/** Build data-aeon-* attributes for styling unstyled parts. */
+declare function partAttrs(scope: string, part: string, options?: AttrOptions): Record<string, unknown>;
+
+type AeonSnapshot<M extends AnyStateMachine> = SnapshotFrom<M>;
+type AeonActor<M extends AnyStateMachine> = ActorRefFrom<M>;
+/** Flatten nested state value for data-aeon-state attribute. */
+declare function stateToAttr(value: unknown): string;
+
+/** Stable conditions the machine may occupy — mutually exclusive at a given depth. */
+type AeonStateValue = string | {
+    [key: string]: AeonStateValue;
+};
+/** Events that may cause transitions. */
+type AeonEvent = {
+    type: string;
+} & Record<string, unknown>;
+/**
+ * Machine context at a snapshot. Presentation is derived from this plus the active
+ * state value — never the other way around.
+ */
+type AeonContext<T extends Record<string, unknown> = Record<string, unknown>> = T;
+/**
+ * Attribute contract for unstyled parts. `data-aeon-state` should enumerate the
+ * full stable condition (e.g. `open`, `checked`, `idle loading`) so styles and
+ * assistive tech reflect the complete machine definition, not a partial guess.
+ */
+interface AeonDataAttrs {
+    'data-aeon-scope': string;
+    'data-aeon-part': string;
+    'data-aeon-state'?: string;
+    'data-disabled'?: string;
+    'data-focus'?: string;
+    'data-highlighted'?: string;
+}
+
+/** Scroll axis overflow detected on a viewport element. */
+type ScrollOverflow = 'none' | 'x' | 'y' | 'both';
+interface ScrollSnapshot {
+    overflow: ScrollOverflow;
+    /** Space-separated value for data-aeon-state on scroll viewports. */
+    stateAttr: string;
+    atStartY: boolean;
+    atEndY: boolean;
+    betweenY: boolean;
+    atStartX: boolean;
+    atEndX: boolean;
+    betweenX: boolean;
+}
+/** Derive overflow + edge states from a scrollable element. */
+declare function getScrollSnapshot(el: HTMLElement): ScrollSnapshot;
+
+/**
+ * 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). */
+type NormPoint = {
+    readonly x: number;
+    readonly y: number;
+};
+/** Axis-aligned bounds on the normalized plane (inclusive). */
+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). */
+type NormOrigin = 'bottom-left' | 'top-left';
+declare const NORM_PLANE: {
+    readonly bottomLeft: "bottom-left";
+    readonly topLeft: "top-left";
+};
+/** How regions are composed at a breakpoint — product maps to CSS grid / absolute. */
+type LayoutComposition = 'split' | 'stack' | 'overlay';
+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;
+}
+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>>;
+}
+type LayoutMode = 'compact' | 'wide';
+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;
+}
+declare const DEFAULT_COMPACT_MQ = "(max-width: 39.99rem)";
+declare function clampNorm(point: NormPoint, bounds: NormRect): NormPoint;
+declare function normFromClient(rect: DOMRectReadOnly, clientX: number, clientY: number, options?: {
+    origin?: NormOrigin;
+    bounds?: NormRect;
+}): NormPoint;
+declare function clientFromNorm(rect: DOMRectReadOnly, point: NormPoint, options?: {
+    origin?: NormOrigin;
+}): {
+    clientX: number;
+    clientY: number;
+};
+/** Measure element; returns null if not connected. */
+declare function measureElement(el: Element | null | undefined): DOMRect | null;
+/** Prefer a dedicated region rect; fall back to mat when lane not mounted. */
+declare function resolveRegionRect(primary: DOMRect | null | undefined, fallback: DOMRect | null | undefined): DOMRect | null;
+declare function matchLayoutMode(spec: ResponsiveLayoutSpec, mq?: Pick<MediaQueryList, 'matches'>): LayoutMode;
+declare function getCompactMq(spec: ResponsiveLayoutSpec): MediaQueryList;
+declare function layoutCompositionForMode(spec: ResponsiveLayoutSpec, mode: LayoutMode): LayoutCompositionSpec;
+declare function regionBoundsForMode(spec: ResponsiveLayoutSpec, mode: LayoutMode, regionId: string): NormRect | undefined;
+/**
+ * Value for `data-aeon-layout-mode` on the mat root.
+ * Pair with `data-aeon-layout-composition` from the active spec.
+ */
+declare function layoutModeAttrs(mode: LayoutMode, composition: LayoutComposition): Record<string, string>;
+/** Spread a norm point inside bounds (keeps cluster off edges). */
+declare function insetNormCluster(point: NormPoint, bounds: NormRect, inset?: {
+    x?: number;
+    y?: number;
+}): NormPoint;
+
+type AeonColorMode = 'light' | 'dark';
+/** Class applied to `<html>` to enable theme-transition.css */
+declare const AEON_THEME_TRANSITION_CLASS = "aeon-theme-transition";
+declare function isAeonColorMode(value: string): value is AeonColorMode;
+/** Map next-themes / user prefs to Aeon `data-aeon-mode`. */
+declare function resolveAeonColorMode(theme: string | undefined, systemPrefersDark?: boolean): AeonColorMode;
+/**
+ * Keep `data-aeon-theme` / `data-aeon-mode` in sync with Tailwind `.dark` apps.
+ * Enables smooth transitions when paired with `@aeon-ui/core/theme-transition.css`.
+ */
+declare function syncAeonColorMode(root: HTMLElement, mode: AeonColorMode, options?: {
+    themeId?: string;
+    enableTransitionClass?: boolean;
+}): void;
+/** Cross-fade theme changes when View Transitions API is available. */
+declare function runAeonThemeTransition(apply: () => void): void;
+
+export { AEON_PRINCIPLE, AEON_THEME_TRANSITION_CLASS, type AeonActor, type AeonColorMode, type AeonContext, type AeonDataAttrs, type AeonEvent, type AeonSnapshot, type AeonStateValue, DEFAULT_COMPACT_MQ, type LayoutComposition, type LayoutCompositionSpec, type LayoutMode, NORM_PLANE, type NormOrigin, type NormPoint, type NormRect, type RegionLayoutSlot, type ResponsiveLayoutSpec, type ScrollOverflow, type ScrollSnapshot, UI_IS_FUNCTION_OF_STATE, accordionAnatomy, anatomy, asyncAnatomy, avatarAnatomy, buttonAnatomy, checkboxAnatomy, clampNorm, clientFromNorm, comboboxAnatomy, dialogAnatomy, fieldAnatomy, getCompactMq, getScrollSnapshot, insetNormCluster, isAeonColorMode, layoutCompositionForMode, layoutModeAttrs, matchLayoutMode, measureElement, menuAnatomy, normFromClient, partAttrs, partOnlyAttrs, pinInputAnatomy, playSurfaceAnatomy, popoverAnatomy, progressAnatomy, radioGroupAnatomy, regionBoundsForMode, resolveAeonColorMode, resolveRegionRect, runAeonThemeTransition, scopeAttrs, scrollAnatomy, selectAnatomy, separatorAnatomy, sliderAnatomy, stateToAttr, switchAnatomy, syncAeonColorMode, tabsAnatomy, toastAnatomy, tooltipAnatomy };