aeon-ui-engine 1.0.3 → 1.1.0

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

@@ -1,5 +1,13 @@
 import { describe, expect, it } from 'vitest'
-import { stateToAttr } from './machine.js'
+import {
+  fieldFace,
+  fieldRegions,
+  getRegionValue,
+  regionLeaf,
+  regionMatches,
+  regionPath,
+  stateToAttr,
+} from './machine.js'
 
 describe('stateToAttr', () => {
   it('stringifies string states', () => {
@@ -16,3 +24,56 @@ describe('stateToAttr', () => {
     ).toBe('interaction:dirty validation:invalid submission:idle')
   })
 })
+
+describe('fieldFace', () => {
+  it('projects a single leaf face (pending > invalid > dirty > idle)', () => {
+    expect(fieldFace({ interaction: 'pristine', validation: 'valid', submission: 'idle' })).toBe(
+      'idle',
+    )
+    expect(fieldFace({ interaction: 'dirty', validation: 'valid', submission: 'idle' })).toBe(
+      'dirty',
+    )
+    expect(fieldFace({ interaction: 'dirty', validation: 'invalid', submission: 'idle' })).toBe(
+      'invalid',
+    )
+    expect(fieldFace({ interaction: 'dirty', validation: 'valid', submission: 'pending' })).toBe(
+      'pending',
+    )
+  })
+
+  it('exposes orthogonal regions separately', () => {
+    expect(
+      fieldRegions({ interaction: 'dirty', validation: 'invalid', submission: 'idle' }),
+    ).toEqual({
+      interaction: 'dirty',
+      validation: 'invalid',
+      submission: 'idle',
+    })
+  })
+})
+
+describe('region helpers', () => {
+  const value = {
+    session: { authenticating: 'verifyCode' },
+    route: 'discover',
+    deck: { ready: 'matched' },
+  }
+
+  it('reads a region value', () => {
+    expect(getRegionValue(value, 'route')).toBe('discover')
+    expect(getRegionValue(value, 'deck')).toEqual({ ready: 'matched' })
+  })
+
+  it('walks compound paths to a leaf', () => {
+    expect(regionPath(value, 'deck')).toEqual(['ready', 'matched'])
+    expect(regionLeaf(value, 'deck')).toBe('matched')
+    expect(regionLeaf(value, 'session')).toBe('verifyCode')
+    expect(regionLeaf(value, 'route')).toBe('discover')
+  })
+
+  it('matches leaves and path prefixes', () => {
+    expect(regionMatches(value, 'deck', 'matched')).toBe(true)
+    expect(regionMatches(value, 'deck', ['ready', 'matched'])).toBe(true)
+    expect(regionMatches(value, 'deck', 'loading')).toBe(false)
+  })
+})

package/packages/core/src/machine.ts

@@ -13,3 +13,96 @@ export function stateToAttr(value: unknown): string {
     .map(([k, v]) => `${k}:${stateToAttr(v)}`)
     .join(' ')
 }
+
+/**
+ * Primary visual face for parallel field charts — same hierarchy as Button/Dialog:
+ * one leaf on `data-aeon-state`, not a region dump.
+ * Priority: pending > invalid > dirty > idle.
+ */
+export type FieldFace = 'idle' | 'dirty' | 'invalid' | 'pending'
+
+export function fieldFace(value: unknown): FieldFace {
+  if (value == null || typeof value !== 'object') return 'idle'
+  const v = value as Record<string, unknown>
+  if (v.submission === 'pending') return 'pending'
+  if (v.validation === 'invalid') return 'invalid'
+  if (v.interaction === 'dirty') return 'dirty'
+  return 'idle'
+}
+
+/** Orthogonal field regions for advanced CSS (`data-aeon-interaction`, etc.). */
+export function fieldRegions(value: unknown): {
+  interaction: string
+  validation: string
+  submission: string
+} {
+  if (value == null || typeof value !== 'object') {
+    return { interaction: 'pristine', validation: 'valid', submission: 'idle' }
+  }
+  const v = value as Record<string, unknown>
+  return {
+    interaction: typeof v.interaction === 'string' ? v.interaction : 'pristine',
+    validation: typeof v.validation === 'string' ? v.validation : 'valid',
+    submission: typeof v.submission === 'string' ? v.submission : 'idle',
+  }
+}
+
+/** Read one region from a (possibly parallel) snapshot value. */
+export function getRegionValue(value: unknown, region: string): unknown {
+  if (value == null) return undefined
+  if (typeof value === 'string') return value === region ? value : undefined
+  if (typeof value === 'object') {
+    return (value as Record<string, unknown>)[region]
+  }
+  return undefined
+}
+
+/**
+ * Active path under a region — e.g. `{ deck: { ready: 'matched' } }` →
+ * `regionPath(v, 'deck')` → `['ready', 'matched']`.
+ */
+export function regionPath(value: unknown, region: string): string[] {
+  const path: string[] = []
+  let cur: unknown = getRegionValue(value, region)
+  while (cur != null) {
+    if (typeof cur === 'string') {
+      path.push(cur)
+      break
+    }
+    if (typeof cur !== 'object') break
+    const entries = Object.entries(cur as Record<string, unknown>)
+    if (entries.length === 0) break
+    if (entries.length > 1) {
+      path.push(entries.map(([k]) => k).sort().join('+'))
+      break
+    }
+    const [key, next] = entries[0]!
+    path.push(key)
+    cur = next
+  }
+  return path
+}
+
+/** Deepest active key under a region (`['ready','matched']` → `'matched'`). */
+export function regionLeaf(value: unknown, region: string): string | undefined {
+  const path = regionPath(value, region)
+  return path[path.length - 1]
+}
+
+/** True when the region path equals or ends with the given leaf / path prefix. */
+export function regionMatches(
+  value: unknown,
+  region: string,
+  match: string | readonly string[],
+): boolean {
+  const path = regionPath(value, region)
+  if (path.length === 0) return false
+  if (typeof match === 'string') {
+    return path.includes(match) || path[path.length - 1] === match
+  }
+  if (match.length === 0) return false
+  if (match.length <= path.length) {
+    return match.every((part, i) => path[i] === part)
+  }
+  return false
+}

package/packages/core/src/theme.ts

@@ -51,3 +51,108 @@ export function runAeonThemeTransition(apply: () => void): void {
 
   apply()
 }
+
+/* ------------------------------------------------------------------ */
+/*  Theme catalog — pure DOM runtime, no Panda dependency               */
+/* ------------------------------------------------------------------ */
+
+export type AeonPalette = {
+  bg: string
+  surface: string
+  surfaceRaised: string
+  border: string
+  text: string
+  muted: string
+  accent: string
+  accentDim: string
+  danger: string
+  dangerDim: string
+  focusRing: string
+  gridLine: string
+}
+
+export interface AeonThemeDefinition {
+  id: string
+  label: string
+  description: string
+  light: AeonPalette
+  dark: AeonPalette
+}
+
+const STORAGE_THEME = 'aeon-theme'
+const STORAGE_MODE = 'aeon-mode'
+
+const DEFAULT_THEME_ID = 'default'
+const DEFAULT_MODE: AeonColorMode = 'dark'
+
+/**
+ * Register theme definitions. Call once at app init.
+ * Returns the registered themes array and lookup map.
+ */
+export function registerAeonThemes(themes: AeonThemeDefinition[]) {
+  const map = Object.fromEntries(themes.map((t) => [t.id, t])) as Record<string, AeonThemeDefinition>
+  const ids = themes.map((t) => t.id)
+  return { themes, map, ids }
+}
+
+export function isAeonThemeId(value: string): boolean {
+  return value !== undefined
+}
+
+export function isAeonMode(value: string): value is AeonColorMode {
+  return value === 'light' || value === 'dark'
+}
+
+/**
+ * Apply a theme + mode to `<html>`. Persists to localStorage.
+ */
+export function applyAeonTheme(
+  themeId: string,
+  mode: AeonColorMode,
+  themeMap?: Record<string, AeonThemeDefinition>,
+) {
+  const root = document.documentElement
+  root.dataset.aeonTheme = themeId
+  root.dataset.aeonMode = mode
+  root.style.colorScheme = mode
+
+  if (themeMap && themeMap[themeId]) {
+    const meta = document.querySelector('meta[name="theme-color"]')
+    if (meta) {
+      meta.setAttribute('content', themeMap[themeId][mode].bg)
+    }
+  }
+
+  try {
+    localStorage.setItem(STORAGE_THEME, themeId)
+    localStorage.setItem(STORAGE_MODE, mode)
+  } catch {
+    /* private mode */
+  }
+}
+
+/**
+ * Read saved prefs or system preference, apply to `<html>`, return current values.
+ */
+export function initAeonTheme(
+  themeMap?: Record<string, AeonThemeDefinition>,
+): { themeId: string; mode: AeonColorMode } {
+  let themeId = DEFAULT_THEME_ID
+  let mode: AeonColorMode = DEFAULT_MODE
+
+  try {
+    const storedTheme = localStorage.getItem(STORAGE_THEME)
+    const storedMode = localStorage.getItem(STORAGE_MODE)
+    if (storedTheme) themeId = storedTheme
+    if (storedMode && isAeonMode(storedMode)) {
+      mode = storedMode
+    } else if (!storedMode && window.matchMedia('(prefers-color-scheme: light)').matches) {
+      mode = 'light'
+    }
+  } catch {
+    if (window.matchMedia('(prefers-color-scheme: light)').matches) mode = 'light'
+  }
+
+  applyAeonTheme(themeId, mode, themeMap)
+  return { themeId, mode }
+}

package/packages/panda/aeon.css

@@ -0,0 +1,7 @@
+/* aeon-ui-engine — single CSS entry point */
+/* Import this one file in your app: import 'aeon-ui-engine/aeon.css' */
+
+@import './styled-system/styles.css';
+@import './theme-runtime.css';
+@import './src/theme/scrollbars.css';
+@import './src/theme/chrome.css';

package/packages/panda/package.json

@@ -33,7 +33,7 @@
     "scripts"
   ],
   "devDependencies": {
-    "@pandacss/dev": "^0.53.4",
+    "@pandacss/dev": "^1.11.2",
     "tsx": "^4.19.4",
     "typescript": "^5.8.3"
   }

package/packages/panda/panda.config.ts

@@ -1,7 +1,21 @@
 import { defineConfig } from '@pandacss/dev'
 import {
   accordionRecipe,
+  avatarRecipe,
+  identityRecipe,
+  metricStripRecipe,
+  listRowRecipe,
+  entryRecipe,
+  conversationRecipe,
+  threadRecipe,
+  composerRecipe,
+  profileHeaderRecipe,
   badgeRecipe,
+  barRecipe,
+  panelRecipe,
+  appShellRecipe,
+  contentRecipe,
+  navRecipe,
   buttonRecipe,
   buttonGroupRecipe,
   asyncRegionRecipe,
@@ -22,6 +36,7 @@ import {
   popoverRecipe,
   tooltipRecipe,
   toastRecipe,
+  themeSwitcherRecipe,
 } from './src/recipes/index.js'
 import { semanticTokens } from './src/theme/semantic-tokens.js'
 import { tokens } from './src/theme/tokens.js'
@@ -42,6 +57,15 @@ export default defineConfig({
     recipes: {
       aeonButton: [{ size: ['*'], variant: ['*'] }],
       aeonBadge: [{ variant: ['*'] }],
+      aeonAvatar: [{ size: ['*'] }],
+      aeonBar: [{ size: ['*'], collapse: ['*'], placement: ['*'] }],
+      aeonPanel: [{ size: ['*'] }],
+      aeonAppShell: [{ contentAlign: ['*'] }],
+      aeonContent: [{ align: ['*'] }],
+      aeonNav: [{ size: ['*'], layout: ['*'] }],
+      aeonProfileHeader: [{ align: ['*'] }],
+      aeonEntry: [{ density: ['*'], layout: ['*'] }],
+      aeonThemeSwitcher: [{ size: ['*'] }],
     },
   },
   conditions: {
@@ -50,6 +74,16 @@ export default defineConfig({
       aeonChecked: '&[data-aeon-state~="checked"]',
       aeonOpen: '&[data-aeon-state=open]',
       aeonClosed: '&[data-aeon-state=closed]',
+      aeonExpanded: '&[data-aeon-state=expanded]',
+      aeonCollapsed: '&[data-aeon-state=collapsed]',
+      aeonOverlayOpen: '&[data-aeon-state=overlayOpen]',
+      aeonFloating: '&[data-aeon-state=floating]',
+      aeonDocked: '&[data-aeon-state=docked]',
+      aeonHidden: '&[data-aeon-state=hidden]',
+      aeonReady: '&[data-aeon-state=ready]',
+      aeonEmpty: '&[data-aeon-state=empty]',
+      aeonActive: '&[data-aeon-state=active]',
+      aeonInactive: '&[data-aeon-state=inactive]',
       aeonPending: '&[data-aeon-state=pending]',
       aeonSuccess: '&[data-aeon-state=success]',
       aeonFailure: '&[data-aeon-state=failure]',
@@ -66,6 +100,20 @@ export default defineConfig({
         aeonBadge: badgeRecipe,
       },
       slotRecipes: {
+        aeonAvatar: avatarRecipe,
+        aeonIdentity: identityRecipe,
+        aeonMetricStrip: metricStripRecipe,
+        aeonListRow: listRowRecipe,
+        aeonEntry: entryRecipe,
+        aeonConversation: conversationRecipe,
+        aeonThread: threadRecipe,
+        aeonComposer: composerRecipe,
+        aeonProfileHeader: profileHeaderRecipe,
+        aeonBar: barRecipe,
+        aeonPanel: panelRecipe,
+        aeonAppShell: appShellRecipe,
+        aeonContent: contentRecipe,
+        aeonNav: navRecipe,
         aeonAccordion: accordionRecipe,
         aeonDialog: dialogRecipe,
         aeonTabs: tabsRecipe,
@@ -85,6 +133,7 @@ export default defineConfig({
         aeonPopover: popoverRecipe,
         aeonTooltip: tooltipRecipe,
         aeonToast: toastRecipe,
+        aeonThemeSwitcher: themeSwitcherRecipe,
       },
     },
   },
@@ -231,14 +280,22 @@ export default defineConfig({
     '[data-aeon-scope="field"] [data-aeon-part="control"][aria-invalid="true"]': {
       borderColor: 'danger',
     },
-    '[data-aeon-scope="field"][data-aeon-state*="submission:pending"] [data-aeon-part="control"]': {
+    '[data-aeon-scope="field"][data-aeon-state="pending"] [data-aeon-part="control"], [data-aeon-scope="field"][data-aeon-submission="pending"] [data-aeon-part="control"]': {
       opacity: '0.7',
       pointerEvents: 'none',
     },
+    '[data-aeon-scope="field"][data-aeon-state="invalid"] [data-aeon-part="control"], [data-aeon-scope="field"][data-aeon-validation="invalid"] [data-aeon-part="control"]':
+      {
+        borderColor: 'danger',
+      },
     '@keyframes aeonProgressIndeterminate': {
       '0%': { transform: 'translateX(-100%)' },
       '100%': { transform: 'translateX(250%)' },
     },
+    '@keyframes aeonToastIn': {
+      '0%': { opacity: '0', transform: 'translateY(0.5rem) scale(0.96)' },
+      '100%': { opacity: '1', transform: 'translateY(0) scale(1)' },
+    },
     '[data-aeon-scope="radioGroup"] [data-aeon-part="item"]': {
       display: 'inline-flex',
       alignItems: 'center',

package/packages/panda/src/recipes/app-shell.ts

@@ -0,0 +1,137 @@
+import { defineSlotRecipe } from '@pandacss/dev'
+
+/**
+ * App shell — layered chrome (header / content / dock / scrim).
+ * Z-index ladder mirrors items-market: content < sticky < header < dock < overlay.
+ */
+const slots = [
+  'root',
+  'header',
+  'subheader',
+  'content',
+  'aside',
+  'footer',
+  'dock',
+  'scrim',
+] as const
+
+export const appShellRecipe = defineSlotRecipe({
+  className: 'aeonAppShell',
+  slots,
+  base: {
+    root: {
+      display: 'flex',
+      flexDir: 'column',
+      minH: '100dvh',
+      width: '100%',
+      position: 'relative',
+      bg: 'bg',
+      color: 'fg',
+      '&[data-aeon-state=overlayOpen] [data-aeon-part=content]': {
+        pointerEvents: 'none',
+        filter: 'blur(2px)',
+        opacity: 0.92,
+      },
+    },
+    header: {
+      /* In-flow chrome band — flex-shrink 0 so shell content never slides underneath. */
+      position: 'relative',
+      flexShrink: 0,
+      zIndex: 50,
+      width: '100%',
+      bg: 'surface',
+      color: 'fg',
+      /* Seam on Bar/StickyBar owns the edge when nested — avoid double rule.
+         StickyBar reuses bar anatomy (data-aeon-scope=bar), not a stickyBar scope. */
+      borderBottomWidth: '1px',
+      borderBottomColor: 'border',
+      '&:has([data-aeon-scope=bar] [data-aeon-part=seam])': {
+        borderBottomWidth: 0,
+      },
+      /* Nested top bar stays in flow; transparent so header surface is the only fill. */
+      '& [data-aeon-scope=bar]': {
+        position: 'relative',
+        top: 'auto',
+        left: 'auto',
+        right: 'auto',
+        bg: 'transparent',
+      },
+    },
+    subheader: {
+      position: 'sticky',
+      top: 'var(--aeon-bar-offset, 4rem)',
+      zIndex: 36,
+      width: '100%',
+    },
+    content: {
+      flex: '1 1 auto',
+      minW: 0,
+      minH: 0,
+      display: 'flex',
+      flexDir: 'column',
+      px: '0.85rem',
+      py: '0.85rem',
+      transitionProperty: 'filter, opacity',
+      transitionDuration: '0.2s',
+    },
+    aside: {
+      position: 'sticky',
+      top: 'var(--aeon-bar-offset, 4rem)',
+      zIndex: 34,
+      alignSelf: 'start',
+      maxH: 'calc(100dvh - var(--aeon-bar-offset, 4rem))',
+      overflow: 'auto',
+    },
+    footer: {
+      width: '100%',
+    },
+    dock: {
+      position: 'fixed',
+      left: 0,
+      right: 0,
+      bottom: 0,
+      zIndex: 55,
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      px: '0.55rem',
+      pt: '0.4rem',
+      paddingBottom: 'calc(0.4rem + env(safe-area-inset-bottom, 0px))',
+      bg: 'surface',
+      color: 'fg',
+      borderTopWidth: '1px',
+      borderTopColor: 'border',
+      /* Nested nav fills the dock track */
+      '& > [data-aeon-scope=nav], & > [data-aeon-part=root]': {
+        width: '100%',
+        maxW: '22rem',
+      },
+    },
+    scrim: {
+      position: 'fixed',
+      inset: 0,
+      zIndex: 45,
+      bg: 'black/40',
+      backdropFilter: 'blur(2px)',
+    },
+  },
+  variants: {
+    /** Content column alignment — projects from screen intent (form vs feed). */
+    contentAlign: {
+      start: {
+        content: { alignItems: 'stretch' },
+      },
+      center: {
+        content: {
+          alignItems: 'center',
+          /* safe center — tall content stays scrollable from the top, never under the header */
+          justifyContent: 'safe center',
+          textAlign: 'center',
+        },
+      },
+    },
+  },
+  defaultVariants: {
+    contentAlign: 'start',
+  },
+})

package/packages/panda/src/recipes/avatar.ts

@@ -0,0 +1,131 @@
+import { defineSlotRecipe } from '@pandacss/dev'
+
+const slots = ['root', 'image', 'fallback', 'badge'] as const
+
+/** Circle clip — always round, regardless of consumer border-radius overrides. */
+const circle = {
+  borderRadius: '9999px',
+} as const
+
+export const avatarRecipe = defineSlotRecipe({
+  className: 'aeonAvatar',
+  description: 'Aeon avatar — always-round profile image with initials fallback + presence',
+  slots,
+  base: {
+    root: {
+      display: 'inline-flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      verticalAlign: 'middle',
+      position: 'relative',
+      flexShrink: 0,
+      aspectRatio: '1 / 1',
+      ...circle,
+      fontFamily: 'ui',
+      /* Badge sits on the rim — keep root visible; clip faces on image/fallback. */
+      overflow: 'visible',
+      boxSizing: 'border-box',
+    },
+    image: {
+      display: 'block',
+      width: '100%',
+      height: '100%',
+      objectFit: 'cover',
+      ...circle,
+      overflow: 'hidden',
+    },
+    fallback: {
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      width: '100%',
+      height: '100%',
+      boxSizing: 'border-box',
+      ...circle,
+      overflow: 'hidden',
+      fontWeight: 'semibold',
+      letterSpacing: '-0.04em',
+      lineHeight: '1',
+      textTransform: 'uppercase',
+      color: 'fg',
+      bg: 'surfaceRaised',
+      /* Fit 1–2 initials without clipping */
+      px: '0.15rem',
+      userSelect: 'none',
+    },
+    badge: {
+      position: 'absolute',
+      bottom: 0,
+      right: 0,
+      ...circle,
+      borderWidth: '2px',
+      borderColor: 'bg',
+      bg: 'muted',
+      '&[data-aeon-state=active]': { bg: 'accent' },
+      '&[data-aeon-state=away]': {
+        bg: 'accentDim',
+        outlineWidth: '1px',
+        outlineStyle: 'solid',
+        outlineColor: 'accent',
+      },
+      '&[data-aeon-state=busy]': { bg: 'danger' },
+      '&[data-aeon-state=offline]': { bg: 'border' },
+      '&[data-aeon-state=idle]': { bg: 'muted' },
+    },
+  },
+  variants: {
+    size: {
+      /**
+       * Size styles nest under root so Image/Fallback get the right type even when
+       * styled slots are created without the size variant (ui Avatar pattern).
+       */
+      xs: {
+        root: {
+          width: '1.75rem',
+          height: '1.75rem',
+          '& [data-aeon-part=fallback]': { fontSize: '0.625rem' },
+          '& [data-aeon-part=badge]': {
+            width: '0.45rem',
+            height: '0.45rem',
+            borderWidth: '1px',
+          },
+        },
+      },
+      sm: {
+        root: {
+          width: '2.25rem',
+          height: '2.25rem',
+          '& [data-aeon-part=fallback]': { fontSize: '0.7rem' },
+          '& [data-aeon-part=badge]': { width: '0.55rem', height: '0.55rem' },
+        },
+      },
+      md: {
+        root: {
+          width: '2.75rem',
+          height: '2.75rem',
+          '& [data-aeon-part=fallback]': { fontSize: '0.8125rem' },
+          '& [data-aeon-part=badge]': { width: '0.7rem', height: '0.7rem' },
+        },
+      },
+      lg: {
+        root: {
+          width: '3.25rem',
+          height: '3.25rem',
+          '& [data-aeon-part=fallback]': { fontSize: '0.9375rem' },
+          '& [data-aeon-part=badge]': { width: '0.8rem', height: '0.8rem' },
+        },
+      },
+      xl: {
+        root: {
+          width: '4.25rem',
+          height: '4.25rem',
+          '& [data-aeon-part=fallback]': { fontSize: '1.125rem' },
+          '& [data-aeon-part=badge]': { width: '0.95rem', height: '0.95rem' },
+        },
+      },
+    },
+  },
+  defaultVariants: {
+    size: 'md',
+  },
+})