aeon-ui-engine 1.0.0

package/apps/demo/src/main.tsx

@@ -0,0 +1,14 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+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 './app.css'
+import { App } from './App.js'
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+)

package/apps/demo/src/nav.ts

@@ -0,0 +1,9 @@
+export const navLinks = [
+  { href: '#layers', label: 'Architecture', sectionId: 'layers' },
+  { href: '#diagrams', label: 'Diagrams', sectionId: 'diagrams' },
+  { href: '#playground', label: 'Components', sectionId: 'playground' },
+  { href: '#philosophy', label: 'Foundation', sectionId: 'philosophy' },
+  { href: '#faq', label: 'FAQ', sectionId: 'faq' },
+] as const
+
+export const navSectionIds = navLinks.map((l) => l.sectionId)

package/apps/demo/src/site.ts

@@ -0,0 +1,347 @@
+/** Public demo origin — set VITE_SITE_ORIGIN in Vercel to your deployment URL. */
+export const siteOrigin =
+  (import.meta.env.VITE_SITE_ORIGIN as string | undefined)?.replace(/\/$/, '') ??
+  'https://aeon-ui.com'
+
+export const site = {
+  brand: 'Aeon UI',
+  tagline: 'Future-proof UI infrastructure for the web',
+  url: 'https://github.com/GenericCPU/aeon-ui',
+  siteOrigin,
+  repoCloneUrl: 'https://github.com/GenericCPU/aeon-ui.git',
+  studio: 'SpiderCorp',
+  studioUrl: 'https://spidercorp.xyz',
+
+  heroEyebrow: 'Future-proof UI · Statecharts · Design systems',
+  heroTitle: 'Future-proof UI for the modern web.',
+  heroAccent: 'Built to last.',
+  heroLead:
+    'Statechart-driven primitives and a styled layer your team controls — dependable behavior today, room to grow tomorrow.',
+  heroSub:
+    'Grounded in proven state theory and production-ready patterns for compound components, anatomy, and styling.',
+  heroCtaPrimary: 'See components',
+  heroCtaSecondary: 'View architecture',
+  heroInstallLabel: 'Early access',
+  heroInstallAccess: 'DM FOR EARLY ACCESS',
+  stateCardLabel: 'Example: fetch region',
+  stateCardHint: 'Five states on the rail. One active. Click Run.',
+
+  heroStats: [
+    {
+      label: 'Headless',
+      detail: 'Compound primitives and anatomy tokens — your brand, your CSS',
+      example: '<Switch.Root>\n  <Switch.Control />\n</Switch.Root>',
+    },
+    {
+      label: 'Machines',
+      detail: 'Explicit states, guards, and hierarchy powered by XState',
+      example: "send({ type: 'FETCH' })",
+    },
+    {
+      label: 'Styled',
+      detail: 'Panda CSS slot recipes with thoughtful defaults you can extend',
+      example: "import { Button } from '@aeon-ui/ui'",
+    },
+  ],
+
+  layersLabel: 'Architecture',
+  layersTitle: 'Three layers. One coherent system.',
+  layersLead:
+    'Headless behavior, explicit anatomy, and intentional styling — composed so your product can evolve without rewriting its foundations.',
+
+  diagramsLabel: 'Statecharts',
+  diagramsTitle: 'Diagrams from Aeon',
+  diagramsLead:
+    'Executable XState models in @aeon-ui/primitives — rendered here as statecharts you can compare to live demos in the playground.',
+  statesDocUrl: 'https://github.com/GenericCPU/aeon-ui/blob/main/STATES.md',
+
+  playgroundLabel: 'Live',
+  playgroundTitle: 'Experience the components',
+  playgroundLead:
+    'Every control runs on an executable XState model. Interact below and see predictable, reviewable behavior in action.',
+
+  philosophyLabel: 'Foundation',
+  philosophyTitle: 'Built on statecharts',
+  philosophyLead:
+    'Thanh Nguyen’s research on statecharts for web applications informs how Aeon models interaction — clear states, clear transitions, lasting maintainability.',
+  thesisUrl:
+    'https://www.theseus.fi/bitstream/handle/10024/334118/Thanh_Nguyen.pdf?sequence=2&isAllowed=y',
+  thesisCta: 'Read the thesis (PDF)',
+
+  faqLabel: 'FAQ',
+  faqTitle: 'Common questions',
+  faqLead: 'Straight answers for teams evaluating durable UI infrastructure.',
+} as const
+
+export const layers = [
+  {
+    id: 'core',
+    title: '@aeon-ui/core',
+    description: 'Philosophy, anatomy, and attributes your theme can target with confidence.',
+    highlights: ['asyncAnatomy, buttonAnatomy, …', 'stateToAttr(snapshot)', 'PHILOSOPHY.md + STATES.md'],
+    example: `import { partAttrs, asyncAnatomy } from '@aeon-ui/core'
+
+partAttrs(asyncAnatomy.scope, asyncAnatomy.readout, {
+  state: 'loading',
+})`,
+  },
+  {
+    id: 'react',
+    title: '@aeon-ui/react',
+    description: 'Headless React bindings where the interface reflects the machine snapshot.',
+    highlights: ['Async, Field, Dialog, Tabs', 'useAeonMachine(machine)', 'Compound parts'],
+    example: `import { Async, useAsyncContext } from '@aeon-ui/react'
+
+<Async.Root>
+  <Async.Track />
+  <Async.Readout>{status}</Async.Readout>
+</Async.Root>`,
+  },
+  {
+    id: 'ui',
+    title: '@aeon-ui/ui',
+    description: 'A polished styled layer — ship as-is or make it yours.',
+    highlights: ['Buttons, badges, panels', 'Panda slot recipes', 'Themes: light/dark × preset'],
+    example: `import { Async, Button } from '@aeon-ui/ui'
+
+<Button.Root status="pending">Saving…</Button.Root>`,
+  },
+] as const
+
+export const commitments = [
+  {
+    id: 'exclusive',
+    title: 'Clear states, clear UI',
+    description:
+      'Each region holds one stable condition at a time — interfaces stay coherent as features grow.',
+  },
+  {
+    id: 'diagram',
+    title: 'Diagrammable by design',
+    description:
+      'Behavior you can review, extend, and visualize alongside your team before adding complexity.',
+  },
+  {
+    id: 'defaults',
+    title: 'Your design system, fully yours',
+    description:
+      'Unstyled primitives plus intentional tokens — every surface reflects your brand and your standards.',
+  },
+] as const
+
+export const philosophyTenets = [
+  {
+    title: 'Write the chart first',
+    body: 'Decide every stable state and transition before you pick colors.',
+    example: `states: { idle: {}, loading: {}, success: {}, failure: {} }`,
+  },
+  {
+    title: 'UI = f(state)',
+    body: 'Components read one snapshot. Labels, disabled flags, and CSS all agree.',
+    example: `data-aeon-state="loading"`,
+  },
+  {
+    title: 'Show the full map',
+    body: 'Users see every state the machine allows — especially for async and forms.',
+    example: `<Async.Track />  {/* idle · loading · success · … */}`,
+  },
+  {
+    title: 'Scale with regions',
+    body: 'Split interaction, validation, and submission instead of one overloaded “error”.',
+    example: `interaction:dirty validation:invalid submission:pending`,
+  },
+] as const
+
+export const playgroundBlocks = {
+  async: {
+    title: 'Async region',
+    description:
+      'A fetch flow with five states. The rail always shows the full lifecycle; the readout and buttons match the active one.',
+    example: `import { Async, Button } from '@aeon-ui/ui'
+
+<Async.Root>
+  <Async.Track />
+  <Async.Readout>Ready</Async.Readout>
+  <Async.Actions>
+    <Button.Root onClick={() => send({ type: 'FETCH' })}>
+      Fetch
+    </Button.Root>
+  </Async.Actions>
+</Async.Root>`,
+  },
+  buttonLifecycle: {
+    title: 'Button lifecycle',
+    description:
+      'Submit buttons need more than disabled. pending, success, and failure are real states — styled and announced.',
+    example: `<Button.Root status="pending" aria-busy>
+  Submitting…
+</Button.Root>`,
+  },
+  scroll: {
+    title: 'Scroll regions',
+    description:
+      'Theme-aware scrollbars on vertical, horizontal, and 2D overflow. Scroll position and axis show up on data-aeon-state (e.g. between-y, at-start-x).',
+    example: `import { Scroll } from '@aeon-ui/ui'
+
+<Scroll.Root axis="both" maxH="md">
+  <Scroll.Viewport>
+    <Scroll.Content>{children}</Scroll.Content>
+  </Scroll.Viewport>
+  <Scroll.StateReadout />
+</Scroll.Root>`,
+  },
+  field: {
+    title: 'Field regions',
+    description:
+      'Three parallel regions: touched or not, valid or not, submitting or not. The root carries all three in data-aeon-state.',
+    example: `<Field.Root>
+  <Field.Label htmlFor="email">Email</Field.Label>
+  <Field.Control id="email" validate={isEmail} />
+  <Field.Message>Invalid email.</Field.Message>
+</Field.Root>`,
+  },
+  buttons: {
+    title: 'Buttons',
+    description: 'Variants and sizes. Wrap groups in Button.Group for spacing.',
+    example: `<Button.Group>
+  <Button.Root>Primary</Button.Root>
+  <Button.Root variant="outline">Outline</Button.Root>
+  <Button.Root variant="ghost">Ghost</Button.Root>
+</Button.Group>`,
+  },
+  toggle: {
+    title: 'Switch & checkbox',
+    description: 'Checked state lives in the machine. Pressed state is tracked for the thumb.',
+    example: `<Switch.Root defaultChecked>
+  <Switch.Control><Switch.Thumb /></Switch.Control>
+  <Switch.Label>Notifications</Switch.Label>
+</Switch.Root>`,
+  },
+  dialog: {
+    title: 'Dialog',
+    description: 'open and closed are explicit. Escape and backdrop clicks are defined transitions.',
+    example: `<Dialog.Root>
+  <Dialog.Trigger>Open</Dialog.Trigger>
+  <Dialog.Content>
+    <Dialog.Title>Title</Dialog.Title>
+    <Dialog.CloseTrigger>Close</Dialog.CloseTrigger>
+  </Dialog.Content>
+</Dialog.Root>`,
+  },
+  combobox: {
+    title: 'Combobox',
+    description:
+      'Typeahead select built on the same listbox model as Select — filter options, arrow keys, Enter to commit.',
+    example: `import { Combobox } from '@aeon-ui/ui'
+
+<Combobox.Root value={value} onValueChange={setValue}>
+  <Combobox.Input placeholder="Search…" aria-label="Country" />
+  <Combobox.Content>
+    <Combobox.Item value="us">United States</Combobox.Item>
+    <Combobox.Empty />
+  </Combobox.Content>
+</Combobox.Root>`,
+  },
+  overlay: {
+    title: 'Menu, popover, tooltip & toast',
+    description:
+      'Floating surfaces share an open/closed machine. Menu uses menu roles; toast uses polite live region.',
+    example: `import { Menu, Tooltip, Toast, useToast } from '@aeon-ui/ui'
+
+// App root:
+<Toast.Provider>
+  <App />
+  <Toast.Viewport placement="bottom-end" />
+</Toast.Provider>
+
+// Anywhere inside the provider:
+const { publish } = useToast()
+publish({ title: 'Saved', description: 'Changes applied.', durationMs: 4000 })`,
+  },
+  tabsAccordion: {
+    title: 'Tabs & accordion',
+    description: 'One active tab. Multiple accordion items can be open — each item has its own state.',
+    example: `<Tabs.Root defaultValue="a">
+  <Tabs.List>
+    <Tabs.Trigger value="a">Tab A</Tabs.Trigger>
+  </Tabs.List>
+  <Tabs.Content value="a">…</Tabs.Content>
+</Tabs.Root>`,
+  },
+} as const
+
+export const tabsExamples = {
+  philosophy: {
+    label: 'Idea',
+    content: 'Define states in a chart. UI only shows conditions the chart allows.',
+    example: 'UI = f(snapshot)',
+  },
+  machines: {
+    label: 'Machines',
+    content: 'XState runs in the browser. Same model you sketch on a whiteboard.',
+    example: "import { createAsyncMachine } from '@aeon-ui/primitives'",
+  },
+  anatomy: {
+    label: 'Anatomy',
+    content: 'Style with data attributes — stable across refactors.',
+    example: '[data-aeon-scope="button"][data-aeon-state="pending"]',
+  },
+} as const
+
+export const accordionExamples = {
+  what: {
+    trigger: 'What is Aeon UI?',
+    content: 'Headless statechart components for React, plus an optional styled layer.',
+    example: 'git clone https://github.com/GenericCPU/aeon-ui.git',
+  },
+  why: {
+    trigger: 'Why statecharts?',
+    content: 'So async, forms, and modals stay explicit as products grow.',
+    example: 'See STATES.md in the repo for states traditional UI skips.',
+  },
+} as const
+
+export const faq = [
+  {
+    id: 'totality',
+    question: 'What does “UI = f(state)” mean?',
+    answer:
+      'The machine snapshot picks what renders. If the chart has loading, you build loading UI — not a boolean you forgot to clear.',
+    example: `const status = snapshot.value // "loading"
+<Async.Readout>{copy[status]}</Async.Readout>`,
+  },
+  {
+    id: 'structure',
+    question: 'How do components compose?',
+    answer:
+      'Compound parts (Root, Track, Label, …) with data-aeon-scope and data-aeon-part. Behavior comes from XState machines in @aeon-ui/primitives.',
+    example: `<Checkbox.Root>
+  <Checkbox.Control />
+  <Checkbox.Label>Email me</Checkbox.Label>
+</Checkbox.Root>`,
+  },
+  {
+    id: 'styling',
+    question: 'How do I style things?',
+    answer:
+      'Target data-aeon-* in your CSS, or use @aeon-ui/ui recipes. Themes swap palettes on html[data-aeon-theme][data-aeon-mode].',
+    example: `import '@aeon-ui/panda/styles.css'
+import { applyAeonTheme } from '@aeon-ui/panda/themes'
+
+applyAeonTheme('signal', 'dark')`,
+  },
+  {
+    id: 'headless',
+    question: 'Headless only?',
+    answer:
+      'Yes. Import @aeon-ui/react, bring your own CSS, and keep the same anatomy attributes.',
+    example: `import { Dialog } from '@aeon-ui/react'`,
+  },
+  {
+    id: 'roadmap',
+    question: 'What ships today?',
+    answer:
+      '14 headless primitives including Menu, Popover, Tooltip, and Toast; Panda themes; styled @aeon-ui/ui. See COMPONENTS.md for the full matrix.',
+    example: 'pnpm dev  →  localhost:5173',
+  },
+] as const

package/apps/demo/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "paths": {
+      "@aeon-ui/core": ["../../packages/core/src/index.ts"],
+      "@aeon-ui/primitives": ["../../packages/primitives/src/index.ts"],
+      "@aeon-ui/panda": ["../../packages/panda"],
+      "@aeon-ui/panda/themes": ["../../packages/panda/src/theme/index.ts"],
+      "@aeon-ui/panda/styled-system/css": ["../../packages/panda/styled-system/css/index.d.ts"],
+      "@aeon-ui/panda/styled-system/recipes": ["../../packages/panda/styled-system/recipes/index.d.ts"],
+      "@aeon-ui/react": ["../../packages/react/src/index.ts"],
+      "@aeon-ui/ui": ["../../packages/ui/src/index.ts"]
+    }
+  },
+  "include": ["src"]
+}

package/apps/demo/vite-plugins/og-meta.ts

@@ -0,0 +1,30 @@
+import type { Plugin } from 'vite'
+import { loadEnv } from 'vite'
+import { absoluteUrl, openGraphHeadHtml } from '@aeon-ui/site'
+import { og } from '../og.config.mjs'
+
+export function ogMetaPlugin(mode: string): Plugin {
+  const env = loadEnv(mode, process.cwd(), '')
+  const siteOrigin = (env.VITE_SITE_ORIGIN ?? 'https://aeon-ui.com').replace(/\/$/, '')
+
+  return {
+    name: 'aeon-og-meta',
+    transformIndexHtml(html) {
+      const fragment = openGraphHeadHtml({
+        title: og.title,
+        description: og.description,
+        url: absoluteUrl(siteOrigin, '/'),
+        image: absoluteUrl(siteOrigin, og.imagePath),
+        imageAlt: og.imageAlt,
+        siteName: og.siteName,
+        themeColor: og.themeColor,
+      })
+      const canonical = `<link rel="canonical" href="${siteOrigin}/" />`
+      const icon = `<link rel="icon" href="/favicon.svg" type="image/svg+xml" />`
+      return html.replace(
+        '<!-- OG_META -->',
+        `${canonical}\n    ${icon}\n    ${fragment}`,
+      )
+    },
+  }
+}

package/apps/demo/vite.config.ts

@@ -0,0 +1,69 @@
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import react from '@vitejs/plugin-react'
+import { defineConfig } from 'vite'
+import { ogMetaPlugin } from './vite-plugins/og-meta.js'
+
+const root = path.dirname(fileURLToPath(import.meta.url))
+const packages = path.resolve(root, '../../packages')
+
+/** More specific aliases must come first — `@aeon-ui/ui` → index.ts breaks `…/styles.css`. */
+export default defineConfig(({ mode }) => ({
+  plugins: [react(), ogMetaPlugin(mode)],
+  server: {
+    port: 5173,
+    strictPort: false,
+  },
+  resolve: {
+    alias: [
+      {
+        find: '@aeon-ui/panda/styles.css',
+        replacement: path.join(packages, 'panda/styled-system/styles.css'),
+      },
+      {
+        find: '@aeon-ui/panda/theme-runtime.css',
+        replacement: path.join(packages, 'panda/theme-runtime.css'),
+      },
+      {
+        find: '@aeon-ui/panda/scrollbars.css',
+        replacement: path.join(packages, 'panda/src/theme/scrollbars.css'),
+      },
+      {
+        find: '@aeon-ui/panda/chrome.css',
+        replacement: path.join(packages, 'panda/src/theme/chrome.css'),
+      },
+      {
+        find: '@aeon-ui/panda/styled-system/css',
+        replacement: path.join(packages, 'panda/styled-system/css/index.mjs'),
+      },
+      {
+        find: '@aeon-ui/panda/styled-system/recipes',
+        replacement: path.join(packages, 'panda/styled-system/recipes/index.mjs'),
+      },
+      {
+        find: '@aeon-ui/panda/themes',
+        replacement: path.join(packages, 'panda/src/theme/index.ts'),
+      },
+      {
+        find: '@aeon-ui/ui/styles.css',
+        replacement: path.join(packages, 'ui/src/styles.css'),
+      },
+      { find: '@aeon-ui/core', replacement: path.join(packages, 'core/src/index.ts') },
+      { find: '@aeon-ui/primitives', replacement: path.join(packages, 'primitives/src/index.ts') },
+      { find: '@aeon-ui/react', replacement: path.join(packages, 'react/src/index.ts') },
+      { find: '@aeon-ui/ui', replacement: path.join(packages, 'ui/src/index.ts') },
+      { find: '@aeon-ui/panda', replacement: path.join(packages, 'panda') },
+      { find: '@aeon-ui/site', replacement: path.join(packages, 'site/src/index.ts') },
+    ],
+  },
+  optimizeDeps: {
+    include: [
+      '@aeon-ui/core',
+      '@aeon-ui/primitives',
+      '@aeon-ui/react',
+      '@aeon-ui/panda/themes',
+      '@aeon-ui/panda/styled-system/css',
+      '@aeon-ui/panda/styled-system/recipes',
+    ],
+  },
+}))