aeon-ui-engine 1.0.2 → 1.0.3

package/apps/demo/src/main.tsx

@@ -1,14 +0,0 @@
-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

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

package/apps/demo/src/site.ts

@@ -1,218 +0,0 @@
-/** 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'
-
-/** Published npm package (monorepo root). */
-export const npmPackage = 'aeon-ui-engine' as const
-
-export const npmInstallCommand = `npm install ${npmPackage}` as const
-
-/** User-facing code sample — install line plus usage (no internal workspace import paths). */
-export const withInstall = (usage: string) => `${npmInstallCommand}\n\n${usage.trim()}`
-
-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',
-  npmPackage,
-  npmRegistryUrl: `https://www.npmjs.com/package/${npmPackage}`,
-  npmInstallCommand,
-  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: 'Try components',
-  heroCtaSecondary: 'View architecture',
-  headerCtaShort: 'Try',
-  heroInstallLabel: 'npm',
-  heroInstallCommand: npmInstallCommand,
-  heroInstallHint: `${npmPackage} on npm — core, React bindings, styled components, and themes in one install.`,
-  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: `${npmInstallCommand}\nimport { Button } from '@aeon-ui/ui'`,
-    },
-  ],
-
-  philosophyLabel: 'Foundation',
-  philosophyTitle: 'What Aeon is',
-  philosophyLead:
-    'Not a grab bag of widgets — a discipline for interfaces that stay legible as requirements accumulate. Grounded in statechart theory and the conviction that the UI must represent every condition the model allows, and imply none that it does not.',
-  thesisUrl:
-    'https://www.theseus.fi/bitstream/handle/10024/334118/Thanh_Nguyen.pdf?sequence=2&isAllowed=y',
-  thesisCta: 'Read the thesis (PDF)',
-
-  layersLabel: 'Shape',
-  layersTitle: 'Separation on purpose',
-  layersLead:
-    'Three layers so behavior, contract, and brand can evolve independently — without forking the mental model.',
-
-  diagramsLabel: 'Statecharts',
-  diagramsTitle: 'A map the whole team can read',
-  diagramsLead:
-    'Executable models you can review with design and engineering before complexity lands in production — the same chart the playground runs.',
-  statesDocUrl: 'https://github.com/GenericCPU/aeon-ui/blob/main/STATES.md',
-
-  playgroundLabel: 'Proof',
-  playgroundTitle: 'See the discipline in motion',
-  playgroundLead:
-    'Each block is a real machine. Interact to feel what it means when the interface and the chart stay in lockstep.',
-
-  faqLabel: 'FAQ',
-  faqTitle: 'Questions teams ask',
-  faqLead: 'Identity and adoption — not a feature matrix.',
-} as const
-
-/** Why we built the stack this way — sits above the layer cards. */
-export const commitments = [
-  {
-    id: 'coherent',
-    title: 'One condition at a time',
-    description:
-      'Regions hold a single stable state the team can name, test, and extend — so interfaces stay coherent when flows multiply.',
-  },
-  {
-    id: 'shared',
-    title: 'A shared map',
-    description:
-      'Statecharts give designers and engineers the same picture of behavior before edge cases become tribal knowledge.',
-  },
-  {
-    id: 'sovereign',
-    title: 'Sovereign surfaces',
-    description:
-      'Unstyled primitives with a clear anatomy contract. Defaults when you want speed — full control when you do not.',
-  },
-] as const
-
-export const philosophyTenets = [
-  {
-    title: 'Write the chart first',
-    body: 'List every stable state and transition before you choose type scales. The model is the brief; the UI is its faithful projection.',
-  },
-  {
-    title: 'UI = f(state)',
-    body: 'The snapshot decides what renders — labels, disabled affordances, and data-aeon-state together. Not parallel React flags that drift out of sync.',
-  },
-  {
-    title: 'Show the full map',
-    body: 'Users and developers see the same complete lifecycle. Async empty, button failure, field validation — nothing left implicit off-screen.',
-  },
-  {
-    title: 'Scale with regions',
-    body: 'When complexity arrives, split orthogonal concerns — interaction, validation, submission — instead of one overloaded “error” boolean.',
-  },
-] as const
-
-export const layers = [
-  {
-    id: 'core',
-    title: 'Core',
-    description:
-      'The contract between machine and markup — scope, part, and state attributes your theme can target for years.',
-    highlights: ['North star & anatomy', 'PHILOSOPHY.md · STATES.md'],
-  },
-  {
-    id: 'react',
-    title: 'React',
-    description:
-      'Headless bindings where the DOM reflects the snapshot — compound parts, accessibility, and predictable structure.',
-    highlights: ['Snapshot-driven parts', 'useAeonMachine for app logic'],
-  },
-  {
-    id: 'ui',
-    title: 'Styled UI',
-    description:
-      'An optional face with intentional tokens — ship quickly or treat it as a reference implementation for your system.',
-    highlights: ['Panda recipes on anatomy', 'Themes: your palette, your modes'],
-  },
-] as const
-
-export const playgroundBlocks = {
-  async: {
-    title: 'Async region',
-    description:
-      'Fetch flows as a named lifecycle — idle through empty — so “loading” is never the only story the UI tells.',
-  },
-  buttonLifecycle: {
-    title: 'Button lifecycle',
-    description:
-      'Submission is more than disabled: pending, success, and failure are states worth showing, not hidden side effects.',
-  },
-  field: {
-    title: 'Field',
-    description:
-      'Interaction, validation, and submission as parallel regions — complexity without a single tangled error flag.',
-  },
-  controls: {
-    title: 'Inputs & buttons',
-    description:
-      'Toggles, radio group, slider, and pin input — explicit states on every control surface.',
-  },
-  dialog: {
-    title: 'Dialog',
-    description:
-      'Open and closed are first-class. Dismissal paths are transitions, not surprises.',
-  },
-  overlay: {
-    title: 'Overlays',
-    description:
-      'Floating surfaces with the same open/closed discipline — anchored behavior you can reason about.',
-  },
-} as const
-
-export const faq = [
-  {
-    id: 'what',
-    question: 'What is Aeon UI?',
-    answer:
-      'Infrastructure for the web where behavior is modeled explicitly and the interface expresses that model completely. Headless primitives, React bindings, and an optional styled layer — published as aeon-ui-engine.',
-  },
-  {
-    id: 'why',
-    question: 'Why statecharts?',
-    answer:
-      'Because products outgrow boolean soup. Statecharts name conditions, separate regions, and stay diagrammable as requirements grow — the thesis case for modern web UI is documented in our primary reference (linked in Foundation).',
-  },
-  {
-    id: 'totality',
-    question: 'What does “UI = f(state)” mean?',
-    answer:
-      'The machine snapshot picks what renders. If the chart includes loading, you build loading UI — and you do not imply success, failure, or empty unless the chart allows them.',
-  },
-  {
-    id: 'headless',
-    question: 'Do I have to use your styles?',
-    answer:
-      'No. The headless layer is the point: same anatomy and states with your CSS. The styled package is a convenience, not a cage.',
-  },
-  {
-    id: 'install',
-    question: 'How do I adopt it?',
-    answer: `Install ${npmPackage} from npm. Core, React, and styled UI ship together; import the layer that matches where you are in the stack.`,
-    example: npmInstallCommand,
-  },
-] as const

package/apps/demo/tsconfig.json

@@ -1,17 +0,0 @@
-{
-  "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

@@ -1,30 +0,0 @@
-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

@@ -1,69 +0,0 @@
-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',
-    ],
-  },
-}))

package/docs/API_PATTERNS.md

@@ -1,234 +0,0 @@
-# API patterns (copy-paste)
-
-Canonical snippets for agents. Adjust names only when adding new components.
-
----
-
-## Styled app bootstrap
-
-```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 { applyAeonTheme } from '@aeon-ui/panda/themes'
-
-applyAeonTheme('default', 'dark')
-```
-
----
-
-## Compound component (styled)
-
-```tsx
-import { Dialog, Button } from '@aeon-ui/ui'
-
-<Dialog.Root>
-  <Dialog.Trigger asChild>
-    <Button.Root variant="outline">Open</Button.Root>
-  </Dialog.Trigger>
-  <Dialog.Backdrop />
-  <Dialog.Positioner>
-    <Dialog.Content>
-      <Dialog.Title>Title</Dialog.Title>
-      <Dialog.CloseTrigger>Close</Dialog.CloseTrigger>
-    </Dialog.Content>
-  </Dialog.Positioner>
-</Dialog.Root>
-```
-
----
-
-## Headless + custom CSS
-
-```tsx
-import { Menu } from '@aeon-ui/react'
-
-<Menu.Root>
-  <Menu.Trigger>Actions</Menu.Trigger>
-  <Menu.Positioner>
-    <Menu.Content>
-      <Menu.Item onSelect={save}>Save</Menu.Item>
-    </Menu.Content>
-  </Menu.Positioner>
-</Menu.Root>
-```
-
-```css
-[data-aeon-scope="menu"][data-aeon-part="content"][data-aeon-state="open"] {
-  background: var(--panel);
-}
-```
-
----
-
-## Async totality
-
-```tsx
-import { Async, Button } from '@aeon-ui/ui'
-import { useAsyncContext } from '@aeon-ui/react'
-
-function Fetcher() {
-  const { send } = useAsyncContext()
-  return (
-    <Button.Root size="sm" onClick={() => send({ type: 'FETCH' })}>
-      Fetch
-    </Button.Root>
-  )
-}
-
-<Async.Root>
-  <Async.Track />
-  <Async.Readout />
-  <Async.Actions>
-    <Fetcher />
-  </Async.Actions>
-</Async.Root>
-```
-
----
-
-## Field + validation
-
-```tsx
-import { Field } from '@aeon-ui/ui'
-
-<Field.Root>
-  <Field.Label htmlFor="email">Email</Field.Label>
-  <Field.Control id="email" validate={(v) => /^.+@.+$/.test(v)} />
-  <Field.Message>Invalid email</Field.Message>
-  <Field.Hint>We never share your email.</Field.Hint>
-</Field.Root>
-```
-
-```tsx
-<Field.Root>
-  <Field.Label htmlFor="notes">Notes</Field.Label>
-  <Field.Textarea id="notes" rows={5} name="message" />
-</Field.Root>
-```
-
-```tsx
-import { Select } from '@aeon-ui/react'
-
-<Select.Root value={value} onValueChange={setValue}>
-  <Select.Trigger>
-    <Select.ValueText>{label}</Select.ValueText>
-  </Select.Trigger>
-  <Select.Positioner>
-    <Select.Content>
-      <Select.Item value="a">Option A</Select.Item>
-    </Select.Content>
-  </Select.Positioner>
-</Select.Root>
-```
-
-```tsx
-import { Dialog } from '@aeon-ui/react'
-
-<Dialog.Root>
-  <Dialog.Trigger>Open</Dialog.Trigger>
-  <Dialog.Portal>
-    <Dialog.Backdrop />
-    <Dialog.Positioner>
-      <Dialog.Content>
-        <Dialog.Title>Title</Dialog.Title>
-        <Dialog.CloseTrigger>Close</Dialog.CloseTrigger>
-      </Dialog.Content>
-    </Dialog.Positioner>
-  </Dialog.Portal>
-</Dialog.Root>
-```
-
----
-
-## Button lifecycle (prop)
-
-```tsx
-<Button.Root status="pending" aria-busy>
-  Saving…
-</Button.Root>
-```
-
----
-
-## Button lifecycle (machine)
-
-```tsx
-import { Button, useAeonMachine } from '@aeon-ui/react'
-import { buttonLifecycleMachine } from '@aeon-ui/primitives'
-
-function Submit() {
-  const [snapshot, send] = useAeonMachine(buttonLifecycleMachine)
-  const status = snapshot.value as 'idle' | 'pending' | 'success' | 'failure' | 'disabled'
-
-  return (
-    <Button.Root
-      status={status}
-      onClick={() => send({ type: 'PRESS' })}
-    >
-      Submit
-    </Button.Root>
-  )
-}
-```
-
----
-
-## App-owned XState
-
-```tsx
-import { useAeonMachine } from '@aeon-ui/react'
-import { myFeatureMachine } from './machines/my-feature'
-
-const [snapshot, send] = useAeonMachine(myFeatureMachine)
-```
-
----
-
-## Panda recipe in custom component
-
-```tsx
-import { aeonButton } from '@aeon-ui/panda/styled-system/recipes'
-import { Button } from '@aeon-ui/react'
-
-const styles = aeonButton({ variant: 'ghost', size: 'sm' })
-
-<Button.Root className={styles}>Click</Button.Root>
-```
-
----
-
-## New machine + anatomy (minimal)
-
-```ts
-// packages/primitives/src/machines/widget.ts
-import { setup } from 'xstate'
-export const widgetMachine = setup({ types: { events: {} as { type: 'OPEN' } } }).createMachine({
-  id: 'widget',
-  initial: 'closed',
-  states: { closed: { on: { OPEN: 'open' } }, open: { on: { CLOSE: 'closed' } } },
-})
-
-// packages/core/src/anatomy.ts
-export const widgetAnatomy = anatomy('widget', ['root', 'trigger'] as const)
-
-// packages/react — Root uses useAeonMachine(widgetMachine) + partAttrs(widgetAnatomy.scope, ...)
-```
-
-See [COMPONENT_CHECKLIST.md](./COMPONENT_CHECKLIST.md).
-
----
-
-## Scroll region
-
-```tsx
-import { Scroll } from '@aeon-ui/ui'
-
-<Scroll.Root axis="y" maxH="md">
-  <Scroll.Viewport>
-    <Scroll.Content>{children}</Scroll.Content>
-  </Scroll.Viewport>
-</Scroll.Root>
-```