aeon-ui-engine 1.0.3 → 1.2.0

package/packages/core/src/anatomy.ts

@@ -40,6 +40,44 @@ export const dialogAnatomy = anatomy('dialog', [
   'closeTrigger',
 ] as const)
 
+/**
+ * Prompt — confirm / permission / update-style dialog on top of Dialog.
+ * Universal parts: eyebrow, meta, amount, actions (primary + secondary).
+ */
+export const promptAnatomy = anatomy('prompt', [
+  'root',
+  'eyebrow',
+  'meta',
+  'amount',
+  'actions',
+  'primary',
+  'secondary',
+] as const)
+
+/**
+ * AppNav — section + detail stack (list→detail, settings drill-in).
+ */
+export const appNavAnatomy = anatomy('appNav', [
+  'root',
+  'rail',
+  'section',
+  'stage',
+  'breadcrumb',
+  'crumb',
+  'back',
+] as const)
+
+/**
+ * StatusBanner — non-blocking top-of-app notice (update ready, syncing, offline).
+ */
+export const statusBannerAnatomy = anatomy('statusBanner', [
+  'root',
+  'copy',
+  'title',
+  'body',
+  'actions',
+] as const)
+
 export const tabsAnatomy = anatomy('tabs', [
   'root',
   'list',
@@ -81,10 +119,10 @@ export const fieldAnatomy = anatomy('field', [
 export const scrollAnatomy = anatomy('scroll', ['root', 'viewport', 'content'] as const)
 
 /**
- * Play / game surface — mat shell with table, dice, and bank regions.
- * Use with normalized layout coords (@see docs/LAYOUT_COORDINATES.md).
+ * Spatial play surface — universal mat + regions + entities (not a specific game).
+ * App logic names regions; entity labels come from compose `items`. See LAYOUT_COORDINATES.md.
  */
-export const playSurfaceAnatomy = anatomy('play', ['mat', 'table', 'dice', 'bank'] as const)
+export const playSurfaceAnatomy = anatomy('play', ['root', 'mat', 'region', 'entity'] as const)
 
 export const selectAnatomy = anatomy('select', [
   'root',
@@ -140,8 +178,118 @@ export const toastAnatomy = anatomy('toast', [
   'closeTrigger',
 ] as const)
 
-/** Profile image — loaded / loading / error on root `data-aeon-state`. */
-export const avatarAnatomy = anatomy('avatar', ['root', 'image', 'fallback'] as const)
+/** Profile image — loaded / loading / error on root `data-aeon-state`. Badge = presence / status corner. */
+export const avatarAnatomy = anatomy('avatar', ['root', 'image', 'fallback', 'badge'] as const)
+
+/**
+ * Identity strip — avatar + primary/secondary text (items-market AvatarWithName).
+ * Presentational; compose into ProfileHeader / ListRow / AccountCluster.
+ */
+export const identityAnatomy = anatomy('identity', [
+  'root',
+  'avatar',
+  'title',
+  'subtitle',
+  'meta',
+  'trailing',
+] as const)
+
+/**
+ * Profile header — dense account hero (not dating). Media optional; metrics + actions zones.
+ * Spatial: identity leading, metrics inline, actions trailing / bottom leading pair.
+ */
+export const profileHeaderAnatomy = anatomy('profileHeader', [
+  'root',
+  'media',
+  'identity',
+  'metrics',
+  'actions',
+  'body',
+] as const)
+
+/**
+ * Entry — compact multi-value content card (feed post, catalog listing, activity item).
+ * Universal layout only — not a social/marketplace niche.
+ * List stacks cards; Root is one card (idle | selected | muted).
+ * Zones: header (leading · heading · meta) · media · body · values · actions · footer.
+ */
+export const entryAnatomy = anatomy('entry', [
+  'list',
+  'root',
+  'header',
+  'leading',
+  'heading',
+  'title',
+  'subtitle',
+  'meta',
+  'media',
+  'body',
+  'values',
+  'value',
+  'actions',
+  'footer',
+] as const)
+
+/**
+ * Metric strip — ultra-dense value/label chips (items-market im-stat cluster).
+ * Generic stats only — not wallet/currency product niches.
+ */
+export const metricStripAnatomy = anatomy('metricStrip', [
+  'root',
+  'chip',
+  'value',
+  'label',
+] as const)
+
+/**
+ * List row — settings / account menu row (h-12 hit target, leading icon, trailing control).
+ */
+export const listRowAnatomy = anatomy('listRow', [
+  'root',
+  'leading',
+  'label',
+  'description',
+  'trailing',
+] as const)
+
+/**
+ * Conversation — inbox / DM list row (universal messaging chrome, not dating).
+ * Leading avatar · title · preview · meta (time) · badge (unread).
+ * Item state: idle | unread | selected.
+ */
+export const conversationAnatomy = anatomy('conversation', [
+  'root',
+  'item',
+  'leading',
+  'body',
+  'title',
+  'preview',
+  'meta',
+  'badge',
+] as const)
+
+/**
+ * Thread — message stream. Items project mine | theirs | pending | failed.
+ */
+export const threadAnatomy = anatomy('thread', [
+  'root',
+  'list',
+  'item',
+  'bubble',
+  'meta',
+  'day',
+] as const)
+
+/**
+ * Composer — bottom compose chrome for threads (input + send).
+ * Root state: idle | sending | disabled | error.
+ */
+export const composerAnatomy = anatomy('composer', [
+  'root',
+  'input',
+  'actions',
+  'send',
+] as const)
 
 export const separatorAnatomy = anatomy('separator', ['root'] as const)
 
@@ -165,3 +313,84 @@ export const sliderAnatomy = anatomy('slider', [
 ] as const)
 
 export const pinInputAnatomy = anatomy('pinInput', ['root', 'input'] as const)
+
+/**
+ * Bar — horizontal layout primitive for toolbars, headers, footers.
+ * Enforces safe flex behavior: no overlap, responsive collapse via overflow.
+ * Parts: root (flex row), leading, center, trailing, optional seam (sticky stack join).
+ * Drive sticky lifecycle with stickyBarMachine → data-aeon-state on root.
+ */
+export const barAnatomy = anatomy('bar', [
+  'root',
+  'leading',
+  'center',
+  'trailing',
+  'seam',
+] as const)
+
+/**
+ * Panel — collapsible layout region for split views.
+ * Group lays out siblings; Root is expanded|collapsed; Label rails vertically when collapsed.
+ */
+export const panelAnatomy = anatomy('panel', [
+  'group',
+  'root',
+  'trigger',
+  'label',
+  'content',
+] as const)
+
+/**
+ * App shell — layered application chrome (items-market MainLayout pattern).
+ * header / subheader / content / aside / footer / dock / scrim under root.
+ */
+export const appShellAnatomy = anatomy('appShell', [
+  'root',
+  'header',
+  'subheader',
+  'content',
+  'aside',
+  'footer',
+  'dock',
+  'scrim',
+] as const)
+
+/**
+ * Content region — status-slotted body. Every contentRegionMachine state has a part.
+ * Pair with Async for fetch; use slots for idle/pending/empty/error/ready/loadingMore/success.
+ */
+export const contentAnatomy = anatomy('content', [
+  'root',
+  'toolbar',
+  'body',
+  'pending',
+  'empty',
+  'error',
+  'success',
+  'sentinel',
+] as const)
+
+/**
+ * Nav — navigational collection (top links, bottom tabs, side rail).
+ * Selection reuses tabsMachine; items project inactive|active|disabled.
+ */
+export const navAnatomy = anatomy('nav', [
+  'root',
+  'item',
+  'indicator',
+  'label',
+  'icon',
+  'badge',
+] as const)
+
+/**
+ * ThemeSwitcher — mode toggle (light/dark) + theme preset selector.
+ * Parts: root, modes (button group), modeBtn, themeSelect, themeTrigger.
+ */
+export const themeSwitcherAnatomy = anatomy('themeSwitcher', [
+  'root',
+  'modes',
+  'modeBtn',
+  'themeSelect',
+  'themeTrigger',
+] as const)

package/packages/core/src/brand-theme.ts

@@ -0,0 +1,172 @@
+/**
+ * Brand → Aeon CSS variable bridge.
+ *
+ * Product apps often already have design tokens. Instead of maintaining a parallel
+ * `--product-*` layer forever, map them onto Aeon’s runtime vars so `@aeon-ui/ui`
+ * recipes and `aeon.css` pick up the brand without forking Panda.
+ */
+import type { AeonColorMode } from './theme.js'
+
+/** Minimal brand fields — anything omitted gets a safe default. */
+export type BrandPaletteInput = {
+  bg: string
+  surface: string
+  surfaceRaised?: string
+  border: string
+  text: string
+  muted: string
+  accent: string
+  accentDim?: string
+  danger?: string
+  dangerDim?: string
+  gridLine?: string
+  /** Optional product fonts (applied as --aeon-font / --aeon-font-display). */
+  font?: string
+  fontDisplay?: string
+  radius?: string
+}
+
+export type BrandPalette = Required<
+  Pick<
+    BrandPaletteInput,
+    | 'bg'
+    | 'surface'
+    | 'surfaceRaised'
+    | 'border'
+    | 'text'
+    | 'muted'
+    | 'accent'
+    | 'accentDim'
+    | 'danger'
+    | 'dangerDim'
+    | 'gridLine'
+  >
+> & {
+  font?: string
+  fontDisplay?: string
+  radius?: string
+  focusRing: string
+}
+
+const DEFAULT_DANGER = { light: '#dc2626', dark: '#f87171' } as const
+
+function focusRing(bg: string, accent: string) {
+  return `0 0 0 2px ${bg}, 0 0 0 4px ${accent}`
+}
+
+/** Normalize a partial brand palette into a full Aeon-compatible palette. */
+export function normalizeBrandPalette(
+  input: BrandPaletteInput,
+  mode: AeonColorMode = 'dark',
+): BrandPalette {
+  const danger = input.danger ?? DEFAULT_DANGER[mode]
+  return {
+    bg: input.bg,
+    surface: input.surface,
+    surfaceRaised: input.surfaceRaised ?? input.surface,
+    border: input.border,
+    text: input.text,
+    muted: input.muted,
+    accent: input.accent,
+    accentDim: input.accentDim ?? `${input.accent}2e`,
+    danger,
+    dangerDim: input.dangerDim ?? `${danger}18`,
+    gridLine:
+      input.gridLine ??
+      (mode === 'light' ? 'rgba(15, 23, 42, 0.07)' : 'rgba(255, 255, 255, 0.05)'),
+    font: input.font,
+    fontDisplay: input.fontDisplay,
+    radius: input.radius,
+    focusRing: focusRing(input.bg, input.accent),
+  }
+}
+
+/** CSS custom properties Aeon recipes already read. */
+export function brandPaletteToCssVars(palette: BrandPalette): Record<string, string> {
+  const vars: Record<string, string> = {
+    '--colors-aeon-bg': palette.bg,
+    '--colors-aeon-surface': palette.surface,
+    '--colors-aeon-surface-raised': palette.surfaceRaised,
+    '--colors-aeon-border': palette.border,
+    '--colors-aeon-text': palette.text,
+    '--colors-aeon-muted': palette.muted,
+    '--colors-aeon-accent': palette.accent,
+    '--colors-aeon-accent-dim': palette.accentDim,
+    '--colors-aeon-danger': palette.danger,
+    '--colors-aeon-danger-dim': palette.dangerDim,
+    '--shadows-focus-ring': palette.focusRing,
+    '--aeon-grid-line': palette.gridLine,
+  }
+  if (palette.font) vars['--aeon-font'] = palette.font
+  if (palette.fontDisplay) vars['--aeon-font-display'] = palette.fontDisplay
+  if (palette.radius) vars['--aeon-radius'] = palette.radius
+  return vars
+}
+
+export type ApplyBrandPaletteOptions = {
+  mode?: AeonColorMode
+  /** Theme id stamped on <html> (default: `brand`). */
+  themeId?: string
+  /** Persist mode/theme to localStorage (default: false — brand apps usually own prefs). */
+  persist?: boolean
+  root?: HTMLElement
+}
+
+/**
+ * Apply a product brand palette to the document so Aeon CSS vars match the app.
+ * Does not require registering a catalog theme — one call at boot is enough.
+ *
+ * @example
+ * applyBrandPalette({
+ *   bg: '#000', surface: '#0a0a0a', border: '#262626',
+ *   text: '#fafafa', muted: '#a1a1aa', accent: '#57ff97',
+ * }, { mode: 'dark' })
+ */
+export function applyBrandPalette(
+  input: BrandPaletteInput,
+  options: ApplyBrandPaletteOptions = {},
+): BrandPalette {
+  const mode = options.mode ?? 'dark'
+  const palette = normalizeBrandPalette(input, mode)
+  if (typeof document === 'undefined') return palette
+
+  const root = options.root ?? document.documentElement
+  const themeId = options.themeId ?? 'brand'
+  root.dataset.aeonTheme = themeId
+  root.dataset.aeonMode = mode
+  root.style.colorScheme = mode
+
+  const vars = brandPaletteToCssVars(palette)
+  for (const [key, value] of Object.entries(vars)) {
+    root.style.setProperty(key, value)
+  }
+
+  const meta = document.querySelector('meta[name="theme-color"]')
+  if (meta) meta.setAttribute('content', palette.bg)
+
+  if (options.persist) {
+    try {
+      localStorage.setItem('aeon-theme', themeId)
+      localStorage.setItem('aeon-mode', mode)
+    } catch {
+      /* private mode */
+    }
+  }
+
+  return palette
+}
+
+/** Serialize palette vars for injecting a `<style>` tag (SSR / non-DOM). */
+export function brandPaletteToCssText(
+  input: BrandPaletteInput,
+  options: { mode?: AeonColorMode; selector?: string } = {},
+): string {
+  const mode = options.mode ?? 'dark'
+  const palette = normalizeBrandPalette(input, mode)
+  const vars = brandPaletteToCssVars(palette)
+  const body = Object.entries(vars)
+    .map(([k, v]) => `  ${k}: ${v};`)
+    .join('\n')
+  const selector = options.selector ?? 'html'
+  return `${selector} {\n  color-scheme: ${mode};\n${body}\n}`
+}

package/packages/core/src/index.ts

@@ -6,3 +6,4 @@ export * from './types.js'
 export * from './scroll.js'
 export * from './layout.js'
 export * from './theme.js'
+export * from './brand-theme.js'

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
+}