aeon-ui-engine 1.0.0

package/packages/core/src/scroll.ts

@@ -0,0 +1,72 @@
+/** Scroll axis overflow detected on a viewport element. */
+export type ScrollOverflow = 'none' | 'x' | 'y' | 'both'
+
+export 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
+}
+
+const EPS = 1
+
+function canScrollY(el: HTMLElement): boolean {
+  return el.scrollHeight > el.clientHeight + EPS
+}
+
+function canScrollX(el: HTMLElement): boolean {
+  return el.scrollWidth > el.clientWidth + EPS
+}
+
+/** Derive overflow + edge states from a scrollable element. */
+export function getScrollSnapshot(el: HTMLElement): ScrollSnapshot {
+  const scrollY = canScrollY(el)
+  const scrollX = canScrollX(el)
+
+  let overflow: ScrollOverflow = 'none'
+  if (scrollY && scrollX) overflow = 'both'
+  else if (scrollY) overflow = 'y'
+  else if (scrollX) overflow = 'x'
+
+  const atStartY = !scrollY || el.scrollTop <= EPS
+  const atEndY = !scrollY || el.scrollTop + el.clientHeight >= el.scrollHeight - EPS
+  const betweenY = scrollY && !atStartY && !atEndY
+
+  const atStartX = !scrollX || el.scrollLeft <= EPS
+  const atEndX = !scrollX || el.scrollLeft + el.clientWidth >= el.scrollWidth - EPS
+  const betweenX = scrollX && !atStartX && !atEndX
+
+  const parts: string[] = []
+  if (overflow === 'none') parts.push('idle')
+  else parts.push(`overflow-${overflow}`)
+
+  if (scrollY) {
+    if (atStartY && atEndY) parts.push('at-start-y', 'at-end-y')
+    else if (atStartY) parts.push('at-start-y')
+    else if (atEndY) parts.push('at-end-y')
+    else parts.push('between-y')
+  }
+
+  if (scrollX) {
+    if (atStartX && atEndX) parts.push('at-start-x', 'at-end-x')
+    else if (atStartX) parts.push('at-start-x')
+    else if (atEndX) parts.push('at-end-x')
+    else parts.push('between-x')
+  }
+
+  return {
+    overflow,
+    stateAttr: parts.join(' '),
+    atStartY,
+    atEndY,
+    betweenY,
+    atStartX,
+    atEndX,
+    betweenX,
+  }
+}

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

@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest'
+import { resolveAeonColorMode } from './theme.js'
+
+describe('resolveAeonColorMode', () => {
+  it('maps explicit themes', () => {
+    expect(resolveAeonColorMode('light', true)).toBe('light')
+    expect(resolveAeonColorMode('dark', false)).toBe('dark')
+  })
+
+  it('falls back to system for system theme', () => {
+    expect(resolveAeonColorMode('system', true)).toBe('dark')
+    expect(resolveAeonColorMode(undefined, false)).toBe('light')
+  })
+})

package/packages/core/src/theme.ts

@@ -0,0 +1,53 @@
+export type AeonColorMode = 'light' | 'dark'
+
+/** Class applied to `<html>` to enable theme-transition.css */
+export const AEON_THEME_TRANSITION_CLASS = 'aeon-theme-transition'
+
+export function isAeonColorMode(value: string): value is AeonColorMode {
+  return value === 'light' || value === 'dark'
+}
+
+/** Map next-themes / user prefs to Aeon `data-aeon-mode`. */
+export function resolveAeonColorMode(
+  theme: string | undefined,
+  systemPrefersDark = false,
+): AeonColorMode {
+  if (theme === 'dark') return 'dark'
+  if (theme === 'light') return 'light'
+  return systemPrefersDark ? 'dark' : 'light'
+}
+
+/**
+ * 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`.
+ */
+export function syncAeonColorMode(
+  root: HTMLElement,
+  mode: AeonColorMode,
+  options?: { themeId?: string; enableTransitionClass?: boolean },
+) {
+  const themeId = options?.themeId ?? root.dataset.aeonTheme ?? 'default'
+  root.dataset.aeonTheme = themeId
+  root.dataset.aeonMode = mode
+  root.style.colorScheme = mode
+
+  if (options?.enableTransitionClass !== false) {
+    root.classList.add(AEON_THEME_TRANSITION_CLASS)
+  }
+}
+
+/** Cross-fade theme changes when View Transitions API is available. */
+export function runAeonThemeTransition(apply: () => void): void {
+  if (typeof document === 'undefined') {
+    apply()
+    return
+  }
+
+  const start = document.startViewTransition
+  if (typeof start === 'function') {
+    start.call(document, apply)
+    return
+  }
+
+  apply()
+}

package/packages/core/src/types.ts

@@ -0,0 +1,25 @@
+/** Stable conditions the machine may occupy — mutually exclusive at a given depth. */
+export type AeonStateValue = string | { [key: string]: AeonStateValue }
+
+/** Events that may cause transitions. */
+export 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.
+ */
+export 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.
+ */
+export interface AeonDataAttrs {
+  'data-aeon-scope': string
+  'data-aeon-part': string
+  'data-aeon-state'?: string
+  'data-disabled'?: string
+  'data-focus'?: string
+  'data-highlighted'?: string
+}

package/packages/core/theme-transition.css

@@ -0,0 +1,58 @@
+/**
+ * Smooth light/dark transitions for apps using CSS variables (Tailwind, etc.).
+ * Add class `aeon-theme-transition` on <html> (see syncAeonColorMode / AeonThemeBridge).
+ */
+
+html.aeon-theme-transition {
+  transition:
+    background-color 0.45s cubic-bezier(0.4, 0, 0.2, 1),
+    color 0.45s cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+html.aeon-theme-transition body {
+  transition:
+    background-color 0.45s cubic-bezier(0.4, 0, 0.2, 1),
+    color 0.45s cubic-bezier(0.4, 0, 0.2, 1),
+    border-color 0.45s cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+html.aeon-theme-transition :where(
+  .bg-background,
+  .bg-card,
+  .bg-popover,
+  .bg-muted,
+  .bg-secondary,
+  .bg-accent,
+  .bg-primary,
+  .text-foreground,
+  .text-muted-foreground,
+  .border-border,
+  [data-slot='card'],
+  [data-slot='avatar-fallback']
+) {
+  transition:
+    background-color 0.45s cubic-bezier(0.4, 0, 0.2, 1),
+    color 0.45s cubic-bezier(0.4, 0, 0.2, 1),
+    border-color 0.45s cubic-bezier(0.4, 0, 0.2, 1),
+    box-shadow 0.45s cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+::view-transition-old(root),
+::view-transition-new(root) {
+  animation-duration: 0.45s;
+  animation-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  html.aeon-theme-transition,
+  html.aeon-theme-transition body,
+  html.aeon-theme-transition :where(.bg-background, .bg-card, .bg-popover, .bg-muted) {
+    transition: none !important;
+  }
+
+  ::view-transition-group(root),
+  ::view-transition-old(root),
+  ::view-transition-new(root) {
+    animation: none !important;
+  }
+}

package/packages/core/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}

package/packages/core/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['src/**/*.test.ts'],
+  },
+})

package/packages/geometry/README.md

@@ -0,0 +1,7 @@
+# @aeon-ui/geometry
+
+Procedural grids, waves, and SVG layout helpers for scene backdrops. Uses `@aeon-ui/core` scene anatomy attributes.
+
+```ts
+import { gridPatternStyle, sceneAttrs, barLayout } from '@aeon-ui/geometry'
+```

package/packages/geometry/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@aeon-ui/geometry",
+  "version": "0.1.0",
+  "description": "Procedural geometric patterns and SVG helpers for Aeon Scene backdrops",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GenericCPU/aeon-ui.git",
+    "directory": "packages/geometry"
+  },
+  "publishConfig": { "access": "public" },
+  "files": ["dist", "README.md"],
+  "keywords": ["aeon-ui", "geometry", "svg", "background", "pattern"],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@aeon-ui/core": "workspace:*"
+  },
+  "devDependencies": {
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3"
+  }
+}

package/packages/geometry/src/index.ts

@@ -0,0 +1,3 @@
+export * from './scene-attrs.js'
+export * from './patterns.js'
+export * from './svg.js'

package/packages/geometry/src/patterns.ts

@@ -0,0 +1,55 @@
+export type GridPatternOptions = {
+  cell?: number
+  lineColor?: string
+  lineWidth?: number
+}
+
+/** CSS `background-image` for an orthogonal grid (no external assets). */
+export function gridPatternStyle(options?: GridPatternOptions): {
+  backgroundImage: string
+  backgroundSize: string
+} {
+  const cell = options?.cell ?? 32
+  const color = options?.lineColor ?? 'rgba(255, 255, 255, 0.06)'
+  const w = options?.lineWidth ?? 1
+  const line = `${w}px ${color}`
+  return {
+    backgroundImage: [
+      `linear-gradient(${line} 0 0)`,
+      `linear-gradient(90deg, ${line} 0 0)`,
+    ].join(', '),
+    backgroundSize: `${cell}px ${cell}px`,
+  }
+}
+
+export type WavePatternOptions = {
+  wavelength?: number
+  amplitude?: number
+  stroke?: string
+  strokeWidth?: number
+}
+
+/** SVG path `d` for a horizontal sine wave across `width`. */
+export function wavePath(width: number, height: number, options?: WavePatternOptions): string {
+  const wavelength = options?.wavelength ?? 48
+  const amplitude = options?.amplitude ?? height * 0.2
+  const mid = height / 2
+  const steps = Math.max(8, Math.ceil(width / (wavelength / 4)))
+  const points: string[] = []
+
+  for (let i = 0; i <= steps; i++) {
+    const t = i / steps
+    const x = t * width
+    const y = mid + Math.sin(t * (width / wavelength) * Math.PI * 2) * amplitude
+    points.push(`${i === 0 ? 'M' : 'L'}${x.toFixed(2)},${y.toFixed(2)}`)
+  }
+  return points.join(' ')
+}
+
+/** Radial vignette as CSS gradient for scene overlays. */
+export function vignetteStyle(options?: { strength?: number }): { background: string } {
+  const s = options?.strength ?? 0.55
+  return {
+    background: `radial-gradient(ellipse 80% 70% at 50% 45%, transparent 0%, rgba(0,0,0,${s}) 100%)`,
+  }
+}

package/packages/geometry/src/scene-attrs.ts

@@ -0,0 +1,11 @@
+import { scopeAttrs } from '@aeon-ui/core'
+
+export type SceneState = 'idle' | 'active' | 'paused'
+
+/** `data-aeon-scope="scene"` for ambient regions (backdrops, visualizers). */
+export function sceneAttrs(
+  part: string,
+  state?: SceneState,
+): Record<string, unknown> {
+  return scopeAttrs('scene', part, state ? { state } : undefined)
+}

package/packages/geometry/src/svg.ts

@@ -0,0 +1,60 @@
+export type BarRect = {
+  x: number
+  y: number
+  w: number
+  h: number
+  fill: string
+}
+
+export type BarLayoutOptions = {
+  count: number
+  viewWidth: number
+  viewHeight: number
+  barWidth?: number
+  gap?: number
+  fills?: readonly string[]
+}
+
+const DEFAULT_FILLS = [
+  '#8B5CF6',
+  '#6366F1',
+  '#4F8FF7',
+  '#38BDF8',
+  '#2DD4BF',
+  '#FBBF24',
+  '#F472B6',
+] as const
+
+/** Evenly spaced vertical bars for spectrum-style SVG (Soundbase-style layout). */
+export function barLayout(options: BarLayoutOptions): BarRect[] {
+  const count = options.count
+  const viewW = options.viewWidth
+  const viewH = options.viewHeight
+  const barW = options.barWidth ?? Math.min(10, (viewW - (count - 1) * (options.gap ?? 4)) / count)
+  const gap = options.gap ?? 4
+  const fills = options.fills ?? DEFAULT_FILLS
+  const totalW = count * barW + (count - 1) * gap
+  const startX = (viewW - totalW) / 2
+  const bars: BarRect[] = []
+
+  for (let i = 0; i < count; i++) {
+    const h = viewH * (0.42 + (i / Math.max(1, count - 1)) * 0.58)
+    const y = (viewH - h) / 2
+    const x = startX + i * (barW + gap)
+    bars.push({
+      x,
+      y,
+      w: barW,
+      h,
+      fill: fills[i % fills.length]!,
+    })
+  }
+  return bars
+}
+
+/** Centered Y scale transform for one bar (scale applied around bar center). */
+export function barScaleTransform(bar: BarRect, scaleY: number): string {
+  const cx = bar.x + bar.w / 2
+  const cy = bar.y + bar.h / 2
+  return `translate(${cx} ${cy}) scale(1 ${scaleY}) translate(${-cx} ${-cy})`
+}

package/packages/geometry/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}

package/packages/panda/README.md

@@ -0,0 +1,66 @@
+# @aeon-ui/panda
+
+**Design tokens and Panda CSS recipes** — workspace-private; ships CSS with `@aeon-ui/ui`.
+
+Agents: run `pnpm codegen` from repo root after any edit here.
+
+## Role
+
+- `defineRecipe` / `defineSlotRecipe` aligned with `@aeon-ui/core` anatomy
+- Generated `styled-system/` (do not hand-edit)
+- Theme moods in `src/theme/themes.config.ts` → `theme-runtime.css`
+
+## Consumption in apps
+
+```tsx
+import '@aeon-ui/panda/styles.css'
+import '@aeon-ui/panda/theme-runtime.css'
+import '@aeon-ui/panda/scrollbars.css'
+import '@aeon-ui/panda/chrome.css'
+
+import { aeonDialog } from '@aeon-ui/panda/styled-system/recipes'
+import { applyAeonTheme, AEON_THEMES } from '@aeon-ui/panda/themes'
+
+applyAeonTheme('ocean', 'dark')
+const styles = aeonDialog()
+```
+
+## Recipe registry
+
+Ground truth: `panda.config.ts` — keys like `aeonButton`, `aeonAsync`, `aeonField`.
+
+Source files: `src/recipes/*.ts` → exported from `src/recipes/index.ts`.
+
+## Conditions (state styling)
+
+Extended conditions in config:
+
+- `aeonOpen`, `aeonClosed`, `aeonPending`, `aeonSuccess`, `aeonFailure`
+- `aeonChecked`, `aeonSelected`, `aeonInvalid`
+
+Target `data-aeon-state` in recipes — not arbitrary product class names.
+
+## Codegen
+
+```bash
+# from repo root
+pnpm codegen
+# or
+pnpm --filter @aeon-ui/panda codegen
+```
+
+Scans: `packages/ui`, `packages/react`, `apps/demo`.
+
+## Add a recipe
+
+1. `src/recipes/<component>.ts` — slot names = anatomy parts
+2. Register in `src/recipes/index.ts` and `panda.config.ts`
+3. `pnpm codegen`
+4. Use in `packages/ui/src/<component>.tsx`
+
+Checklist: [docs/COMPONENT_CHECKLIST.md](../../docs/COMPONENT_CHECKLIST.md).
+
+## Related
+
+- [README.md](../../README.md) — themes section
+- [packages/ui/README.md](../ui/README.md)

package/packages/panda/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@aeon-ui/panda",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "codegen": "panda codegen && panda cssgen && tsx scripts/emit-theme-runtime.ts",
+    "prepare": "panda codegen && panda cssgen && tsx scripts/emit-theme-runtime.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "exports": {
+    "./styles.css": "./styled-system/styles.css",
+    "./theme-runtime.css": "./theme-runtime.css",
+    "./scrollbars.css": "./src/theme/scrollbars.css",
+    "./chrome.css": "./src/theme/chrome.css",
+    "./themes/config": "./src/theme/themes.config.ts",
+    "./styled-system/css": {
+      "types": "./styled-system/css/index.d.ts",
+      "import": "./styled-system/css/index.mjs"
+    },
+    "./styled-system/recipes": {
+      "types": "./styled-system/recipes/index.d.ts",
+      "import": "./styled-system/recipes/index.mjs"
+    },
+    "./preset": "./panda.config.ts",
+    "./themes": "./src/theme/index.ts"
+  },
+  "files": [
+    "styled-system",
+    "theme-runtime.css",
+    "panda.config.ts",
+    "src",
+    "scripts"
+  ],
+  "devDependencies": {
+    "@pandacss/dev": "^0.53.4",
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3"
+  }
+}