aeon-ui-engine 1.0.0

package/packages/site/src/open-graph.ts

@@ -0,0 +1,90 @@
+export type OpenGraphConfig = {
+  title: string
+  description: string
+  /** Canonical page URL (absolute). */
+  url: string
+  /** Share image URL (absolute). Recommend 1200×630 PNG or JPEG. */
+  image: string
+  imageAlt?: string
+  siteName?: string
+  locale?: string
+  type?: 'website' | 'article'
+  twitterCard?: 'summary_large_image' | 'summary'
+  themeColor?: string
+}
+
+export type MetaTag = {
+  tag: 'meta' | 'link'
+  name?: string
+  property?: string
+  content?: string
+  rel?: string
+  href?: string
+}
+
+/** Flat list of meta/link tags for Open Graph + Twitter cards. */
+export function openGraphTags(config: OpenGraphConfig): MetaTag[] {
+  const {
+    title,
+    description,
+    url,
+    image,
+    imageAlt = title,
+    siteName = title,
+    locale = 'en_US',
+    type = 'website',
+    twitterCard = 'summary_large_image',
+    themeColor = '#0c0e12',
+  } = config
+
+  return [
+    { tag: 'meta', name: 'description', content: description },
+    { tag: 'meta', name: 'theme-color', content: themeColor },
+    { tag: 'meta', property: 'og:type', content: type },
+    { tag: 'meta', property: 'og:site_name', content: siteName },
+    { tag: 'meta', property: 'og:locale', content: locale },
+    { tag: 'meta', property: 'og:title', content: title },
+    { tag: 'meta', property: 'og:description', content: description },
+    { tag: 'meta', property: 'og:url', content: url },
+    { tag: 'meta', property: 'og:image', content: image },
+    { tag: 'meta', property: 'og:image:secure_url', content: image },
+    { tag: 'meta', property: 'og:image:type', content: 'image/png' },
+    { tag: 'meta', property: 'og:image:alt', content: imageAlt },
+    { tag: 'meta', property: 'og:image:width', content: '1200' },
+    { tag: 'meta', property: 'og:image:height', content: '630' },
+    { tag: 'meta', name: 'twitter:card', content: twitterCard },
+    { tag: 'meta', name: 'twitter:title', content: title },
+    { tag: 'meta', name: 'twitter:description', content: description },
+    { tag: 'meta', name: 'twitter:image', content: image },
+    { tag: 'meta', name: 'twitter:image:alt', content: imageAlt },
+  ]
+}
+
+export function renderMetaTag(tag: MetaTag): string {
+  if (tag.tag === 'link') {
+    return `<link rel="${tag.rel}" href="${escapeAttr(tag.href ?? '')}" />`
+  }
+  if (tag.property) {
+    return `<meta property="${tag.property}" content="${escapeAttr(tag.content ?? '')}" />`
+  }
+  return `<meta name="${tag.name}" content="${escapeAttr(tag.content ?? '')}" />`
+}
+
+/** HTML fragment to inject before `</head>`. */
+export function openGraphHeadHtml(config: OpenGraphConfig): string {
+  return openGraphTags(config).map(renderMetaTag).join('\n    ')
+}
+
+function escapeAttr(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+}
+
+/** Resolve a public asset path against a site origin. */
+export function absoluteUrl(origin: string, path: string): string {
+  const base = origin.replace(/\/$/, '')
+  const p = path.startsWith('/') ? path : `/${path}`
+  return `${base}${p}`
+}

package/packages/site/tsconfig.json

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

package/packages/solid/README.md

@@ -0,0 +1,30 @@
+# @aeon-ui/solid
+
+Headless **SolidJS** bindings for [Aeon UI](https://github.com/GenericCPU/aeon-ui).
+
+## Install
+
+```bash
+pnpm add @aeon-ui/solid @aeon-ui/core @aeon-ui/primitives xstate solid-js
+```
+
+## Usage
+
+```tsx
+import { Switch } from '@aeon-ui/solid'
+import { createSignal } from 'solid-js'
+
+function Demo() {
+  const [on, setOn] = createSignal(true)
+  return (
+    <Switch.Root checked={on()} onCheckedChange={setOn}>
+      <Switch.Control>
+        <Switch.Thumb />
+      </Switch.Control>
+      <Switch.Label>Notifications</Switch.Label>
+    </Switch.Root>
+  )
+}
+```
+
+See [FRAMEWORKS.md](../../FRAMEWORKS.md).

package/packages/solid/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@aeon-ui/solid",
+  "version": "0.1.0",
+  "description": "Headless SolidJS components backed by Aeon XState machines",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GenericCPU/aeon-ui.git",
+    "directory": "packages/solid"
+  },
+  "publishConfig": { "access": "public" },
+  "files": ["dist", "README.md"],
+  "keywords": ["aeon-ui", "solid", "solidjs", "headless", "xstate", "statechart"],
+  "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 --external solid-js --external xstate --external @xstate/solid --external @aeon-ui/core --external @aeon-ui/primitives",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@aeon-ui/core": "workspace:*",
+    "@aeon-ui/primitives": "workspace:*",
+    "@xstate/solid": "^2.0.0",
+    "xstate": "^5.19.2"
+  },
+  "peerDependencies": {
+    "solid-js": "^1.8.0"
+  },
+  "devDependencies": {
+    "solid-js": "^1.9.5",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3"
+  }
+}

package/packages/solid/src/hooks/use-aeon-machine.ts

@@ -0,0 +1,10 @@
+import { useMachine } from '@xstate/solid'
+import type { AnyStateMachine } from 'xstate'
+
+/** Bridge executable statecharts to Solid — UI = f(snapshot). */
+export function useAeonMachine<M extends AnyStateMachine>(
+  machine: M,
+  options?: Parameters<typeof useMachine<M>>[1],
+) {
+  return useMachine(machine, options)
+}

package/packages/solid/src/index.ts

@@ -0,0 +1,2 @@
+export { useAeonMachine } from './hooks/use-aeon-machine.js'
+export { Switch } from './switch/index.js'

package/packages/solid/src/switch/index.tsx

@@ -0,0 +1,191 @@
+import { partAttrs, switchAnatomy } from '@aeon-ui/core'
+import { toggleMachine } from '@aeon-ui/primitives'
+import {
+  createContext,
+  createEffect,
+  createMemo,
+  useContext,
+  type JSX,
+  type ParentProps,
+} from 'solid-js'
+import { useAeonMachine } from '../hooks/use-aeon-machine.js'
+import { mergeProps } from '../utils/merge-props.js'
+
+interface SwitchContextValue {
+  checked: () => boolean
+  disabled: () => boolean
+  controlled: () => boolean
+  onCheckedChange?: (checked: boolean) => void
+  send: ReturnType<typeof useAeonMachine<typeof toggleMachine>>[1]
+  pressState: () => string
+}
+
+const SwitchCtx = createContext<SwitchContextValue>()
+
+function useSwitchCtx() {
+  const ctx = useContext(SwitchCtx)
+  if (!ctx) throw new Error('Switch parts must be used within Switch.Root')
+  return ctx
+}
+
+export type SwitchRootProps = ParentProps<{
+  checked?: boolean
+  defaultChecked?: boolean
+  disabled?: boolean
+  onCheckedChange?: (checked: boolean) => void
+  class?: string
+}>
+
+function Root(props: SwitchRootProps) {
+  const [snapshot, send] = useAeonMachine(toggleMachine, {
+    input: { checked: props.defaultChecked ?? false, disabled: props.disabled ?? false },
+  })
+
+  const controlled = () => props.checked !== undefined
+  const resolvedChecked = createMemo(() => props.checked ?? snapshot.context.checked)
+  const pressState = createMemo(() =>
+    snapshot.matches({ interaction: 'pressed' }) ? 'pressed' : 'idle',
+  )
+
+  createEffect(() => {
+    if (props.checked !== undefined) send({ type: 'SET_CHECKED', checked: props.checked })
+  })
+
+  createEffect(() => {
+    if (!controlled()) props.onCheckedChange?.(resolvedChecked())
+  })
+
+  const toggle = () => {
+    if (props.disabled) return
+    const next = !resolvedChecked()
+    if (controlled()) props.onCheckedChange?.(next)
+    else send({ type: 'TOGGLE' })
+  }
+
+  const value: SwitchContextValue = {
+    checked: resolvedChecked,
+    disabled: () => props.disabled ?? false,
+    controlled,
+    onCheckedChange: props.onCheckedChange,
+    send,
+    pressState,
+  }
+
+  return (
+    <SwitchCtx.Provider value={value}>
+      <label
+        class={props.class}
+        {...mergeProps(
+          partAttrs(switchAnatomy.scope, switchAnatomy.root, {
+            state: `${resolvedChecked() ? 'checked' : 'unchecked'} ${pressState()}`,
+            disabled: props.disabled,
+          }) as Record<string, unknown>,
+          {
+            onClick: (e: MouseEvent) => {
+              const target = e.target as HTMLElement
+              if (target.closest(`[data-aeon-part="${switchAnatomy.control}"]`)) return
+              toggle()
+            },
+          },
+        )}
+      >
+        {props.children}
+      </label>
+    </SwitchCtx.Provider>
+  )
+}
+
+type ControlProps = JSX.LabelHTMLAttributes<HTMLSpanElement>
+
+function Control(props: ControlProps) {
+  const ctx = useSwitchCtx()
+  const toggle = () => {
+    if (ctx.disabled()) return
+    const next = !ctx.checked()
+    if (ctx.controlled()) ctx.onCheckedChange?.(next)
+    else ctx.send({ type: 'TOGGLE' })
+  }
+  const { class: className, ...rest } = props
+  return (
+    <span
+      role="switch"
+      aria-checked={ctx.checked()}
+      tabIndex={ctx.disabled() ? -1 : 0}
+      class={className}
+      {...mergeProps(
+        partAttrs(switchAnatomy.scope, switchAnatomy.control, {
+          state: `${ctx.checked() ? 'checked' : 'unchecked'} ${ctx.pressState()}`,
+          disabled: ctx.disabled(),
+        }) as Record<string, unknown>,
+        rest as Record<string, unknown>,
+        {
+          onClick: (e: MouseEvent) => {
+            toggle()
+            e.stopPropagation()
+          },
+          onPointerDown: () => {
+            if (!ctx.disabled()) ctx.send({ type: 'POINTER_DOWN' })
+          },
+          onPointerUp: () => ctx.send({ type: 'POINTER_UP' }),
+          onPointerLeave: () => ctx.send({ type: 'POINTER_LEAVE' }),
+          onKeyDown: (e: KeyboardEvent) => {
+            if (e.key === ' ' || e.key === 'Enter') {
+              e.preventDefault()
+              toggle()
+            }
+          },
+        },
+      )}
+    />
+  )
+}
+
+function Thumb(props: JSX.HTMLAttributes<HTMLSpanElement>) {
+  const ctx = useSwitchCtx()
+  const { class: className, ...rest } = props
+  return (
+    <span
+      class={className}
+      {...mergeProps(
+        partAttrs(switchAnatomy.scope, switchAnatomy.thumb, {
+          state: `${ctx.checked() ? 'checked' : 'unchecked'} ${ctx.pressState()}`,
+        }) as Record<string, unknown>,
+        rest as Record<string, unknown>,
+      )}
+    />
+  )
+}
+
+function Label(props: JSX.HTMLAttributes<HTMLSpanElement>) {
+  const { class: className, ...rest } = props
+  return (
+    <span
+      class={className}
+      {...mergeProps(
+        partAttrs(switchAnatomy.scope, switchAnatomy.label) as Record<string, unknown>,
+        rest as Record<string, unknown>,
+      )}
+    />
+  )
+}
+
+function HiddenInput(props: JSX.InputHTMLAttributes<HTMLInputElement>) {
+  const ctx = useSwitchCtx()
+  const { class: className, ...rest } = props
+  return (
+    <input
+      type="checkbox"
+      checked={ctx.checked()}
+      readOnly
+      tabIndex={-1}
+      aria-hidden
+      class={className}
+      {...mergeProps(
+        partAttrs(switchAnatomy.scope, switchAnatomy.hiddenInput) as Record<string, unknown>,
+        rest as Record<string, unknown>,
+      )}
+    />
+  )
+}
+
+export const Switch = { Root, Control, Thumb, Label, HiddenInput }

package/packages/solid/src/utils/merge-props.ts

@@ -0,0 +1,3 @@
+export function mergeProps(...sources: unknown[]): Record<string, unknown> {
+  return Object.assign({}, ...sources) as Record<string, unknown>
+}

package/packages/solid/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "jsx": "preserve",
+    "jsxImportSource": "solid-js",
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}

package/packages/surface/README.md

@@ -0,0 +1,10 @@
+# @aeon-ui/surface
+
+Procedural CSS material presets — no image assets required.
+
+Materials: `stone`, `gravel`, `brick`, `pavement`, `kraft` (cardboard).
+
+```ts
+import '@aeon-ui/surface/surface.css'
+import { surfaceClass, surfaceMaterials } from '@aeon-ui/surface'
+```

package/packages/surface/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@aeon-ui/surface",
+  "version": "0.1.0",
+  "description": "CSS texture presets (stone, gravel, brick) for Aeon Scene backgrounds",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GenericCPU/aeon-ui.git",
+    "directory": "packages/surface"
+  },
+  "publishConfig": { "access": "public" },
+  "files": ["dist", "surface.css", "README.md"],
+  "keywords": ["aeon-ui", "texture", "background", "css"],
+  "type": "module",
+  "sideEffects": ["./surface.css"],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./surface.css": "./surface.css"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3"
+  }
+}

package/packages/surface/src/index.ts

@@ -0,0 +1 @@
+export * from './materials.js'

package/packages/surface/src/materials.ts

@@ -0,0 +1,14 @@
+export const surfaceMaterials = ['stone', 'gravel', 'brick', 'pavement', 'kraft'] as const
+export type SurfaceMaterial = (typeof surfaceMaterials)[number]
+
+const PREFIX = 'aeon-surface'
+
+/** BEM class for a material layer (`aeon-surface aeon-surface--stone`). */
+export function surfaceClass(material: SurfaceMaterial): string {
+  return `${PREFIX} ${PREFIX}--${material}`
+}
+
+/** Optional inline vars to tune a surface on a custom element. */
+export function surfaceStyleVars(material: SurfaceMaterial): Record<string, string> {
+  return { '--aeon-surface-material': material }
+}

package/packages/surface/surface.css

@@ -0,0 +1,113 @@
+/* @aeon-ui/surface — procedural materials (import once per app) */
+
+.aeon-surface {
+  position: relative;
+  background-color: var(--aeon-surface-base, #2a2a2e);
+  background-blend-mode: overlay, soft-light, normal;
+  background-size:
+    4px 4px,
+    12px 12px,
+    cover;
+}
+
+.aeon-surface--stone {
+  --aeon-surface-base: #5c5a56;
+  background-image:
+    radial-gradient(circle at 20% 30%, rgba(255, 255, 255, 0.12) 0%, transparent 45%),
+    radial-gradient(circle at 70% 60%, rgba(0, 0, 0, 0.15) 0%, transparent 40%),
+    linear-gradient(145deg, #6e6c68 0%, #4a4844 50%, #3d3b38 100%);
+  background-size: cover;
+}
+
+.aeon-surface--gravel {
+  --aeon-surface-base: #4a4845;
+  background-image:
+    radial-gradient(circle, rgba(255, 255, 255, 0.08) 1px, transparent 1px),
+    radial-gradient(circle, rgba(0, 0, 0, 0.12) 1px, transparent 1px),
+    linear-gradient(180deg, #5a5752 0%, #3e3c38 100%);
+  background-size:
+    3px 3px,
+    5px 5px,
+    cover;
+  background-position:
+    0 0,
+    2px 2px,
+    0 0;
+}
+
+.aeon-surface--brick {
+  --aeon-surface-base: #6b3a32;
+  background-image:
+    linear-gradient(180deg, rgba(255, 255, 255, 0.05) 1px, transparent 1px),
+    linear-gradient(335deg, rgba(0, 0, 0, 0.3) 11px, transparent 11px),
+    linear-gradient(155deg, rgba(0, 0, 0, 0.24) 11px, transparent 11px),
+    linear-gradient(90deg, #9a5c4a 0%, #7a4038 25%, #8b4a42 50%, #6b3428 75%, #7a4038 100%);
+  background-size:
+    100% 7px,
+    44px 26px,
+    44px 26px,
+    cover;
+  background-position:
+    0 0,
+    0 0,
+    22px 13px,
+    0 0;
+}
+
+/* Asphalt alley ground — aggregate, seams, wear (no image assets). */
+.aeon-surface--pavement {
+  --aeon-surface-base: #2a2a28;
+  background-image:
+    radial-gradient(ellipse 48% 32% at 28% 68%, rgba(255, 255, 255, 0.05) 0%, transparent 72%),
+    radial-gradient(ellipse 42% 28% at 74% 38%, rgba(0, 0, 0, 0.2) 0%, transparent 68%),
+    radial-gradient(circle, rgba(255, 255, 255, 0.07) 0.5px, transparent 0.5px),
+    radial-gradient(circle, rgba(0, 0, 0, 0.13) 0.5px, transparent 0.5px),
+    linear-gradient(180deg, #3a3a36 0%, #2e2e2c 42%, #242422 100%);
+  background-size:
+    100% 100%,
+    100% 100%,
+    4px 4px,
+    5px 5px,
+    cover;
+  background-position:
+    0 0,
+    0 0,
+    0 0,
+    2px 1px,
+    0 0;
+}
+
+/* Kraft cardboard — fiber grain, crease lines (board / marker surfaces). */
+.aeon-surface--kraft {
+  --aeon-surface-base: #b8956a;
+  background-image:
+    repeating-linear-gradient(
+      0deg,
+      transparent 0,
+      transparent 2px,
+      rgba(92, 72, 56, 0.16) 2px,
+      rgba(92, 72, 56, 0.16) 3px
+    ),
+    repeating-linear-gradient(
+      90deg,
+      transparent 0,
+      transparent 7px,
+      rgba(46, 36, 24, 0.06) 7px,
+      rgba(46, 36, 24, 0.06) 8px
+    ),
+    radial-gradient(ellipse 90% 40% at 50% 0%, rgba(160, 120, 70, 0.1) 0%, transparent 55%),
+    radial-gradient(circle, rgba(100, 72, 40, 0.07) 0.8px, transparent 0.8px),
+    linear-gradient(168deg, #c4a070 0%, #b8956a 28%, #a08050 62%, #8a7048 100%);
+  background-size:
+    100% 3px,
+    100% 8px,
+    100% 100%,
+    5px 5px,
+    cover;
+  background-position:
+    0 0,
+    0 1px,
+    0 0,
+    1px 2px,
+    0 0;
+}

package/packages/surface/tsconfig.json

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

package/packages/svelte/README.md

@@ -0,0 +1,45 @@
+# @aeon-ui/svelte
+
+Headless **Svelte** bindings for [Aeon UI](https://github.com/GenericCPU/aeon-ui). Machines live in `@aeon-ui/primitives`; anatomy in `@aeon-ui/core`.
+
+## Install
+
+```bash
+pnpm add @aeon-ui/svelte @aeon-ui/core @aeon-ui/primitives xstate
+```
+
+Peer: `svelte` ^4 or ^5 (Svelte 5 runes used in shipped components).
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import Switch from '@aeon-ui/svelte/Switch.svelte'
+  import SwitchControl from '@aeon-ui/svelte/SwitchControl.svelte'
+  import SwitchThumb from '@aeon-ui/svelte/SwitchThumb.svelte'
+  import SwitchLabel from '@aeon-ui/svelte/SwitchLabel.svelte'
+
+  let on = $state(true)
+</script>
+
+<Switch checked={on} onCheckedChange={(v) => (on = v)}>
+  <SwitchControl><SwitchThumb /></SwitchControl>
+  <SwitchLabel>Notifications</SwitchLabel>
+</Switch>
+```
+
+## `useAeonMachine`
+
+For custom components, subscribe with `$effect`:
+
+```ts
+import { useAeonMachine } from '@aeon-ui/svelte'
+
+const { send, subscribe, getSnapshot } = useAeonMachine(myMachine)
+let snap = $state(getSnapshot())
+$effect(() => subscribe((s) => (snap = s)))
+```
+
+## v0.1 scope
+
+Reference **Switch** port + hook. More components follow [FRAMEWORKS.md](../../FRAMEWORKS.md).

package/packages/svelte/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@aeon-ui/svelte",
+  "version": "0.1.0",
+  "description": "Headless Svelte bindings for Aeon XState machines",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GenericCPU/aeon-ui.git",
+    "directory": "packages/svelte"
+  },
+  "publishConfig": { "access": "public" },
+  "files": ["dist", "src/**/*.svelte", "README.md"],
+  "keywords": ["aeon-ui", "svelte", "headless", "xstate", "statechart"],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "svelte": "./dist/index.js"
+    },
+    "./Switch.svelte": "./src/Switch.svelte",
+    "./SwitchControl.svelte": "./src/SwitchControl.svelte",
+    "./SwitchThumb.svelte": "./src/SwitchThumb.svelte",
+    "./SwitchLabel.svelte": "./src/SwitchLabel.svelte",
+    "./SwitchHiddenInput.svelte": "./src/SwitchHiddenInput.svelte"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean --external svelte --external xstate --external @aeon-ui/core --external @aeon-ui/primitives",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@aeon-ui/core": "workspace:*",
+    "@aeon-ui/primitives": "workspace:*",
+    "xstate": "^5.19.2"
+  },
+  "peerDependencies": {
+    "svelte": "^4.0.0 || ^5.0.0"
+  },
+  "devDependencies": {
+    "@sveltejs/vite-plugin-svelte": "^5.0.3",
+    "svelte": "^5.28.2",
+    "svelte-check": "^4.1.5",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3"
+  }
+}