aeon-ui-engine 1.4.0 → 1.8.0

package/packages/tree/src/interpret.tsx

@@ -0,0 +1,45 @@
+import { partOnlyAttrs, scopeAttrs } from '@aeon-ui/core'
+import { createElement, Fragment, type ReactNode } from 'react'
+import type { Widget } from './widget.js'
+
+export type WidgetHosts = Record<string, () => ReactNode>
+
+/**
+ * Element layer: turn a widget tree into DOM. Anatomy comes from
+ * `@aeon-ui/core`, so product CSS restyles `data-aeon-*` and nothing else
+ * is introduced. Hosts are the escape for existing compounds (Prompt, a
+ * password field) — the tree names the slot, the app supplies the compound.
+ */
+export function interpret(widget: Widget, hosts: WidgetHosts): ReactNode {
+  if (widget.type === 'text') return widget.text
+  if (widget.type === 'host') return hosts[widget.id]?.() ?? null
+
+  const attrs = widget.scope
+    ? scopeAttrs(widget.scope, widget.part ?? 'root', { state: widget.state })
+    : widget.part
+      ? partOnlyAttrs(widget.part, { state: widget.state })
+      : widget.state
+        ? { 'data-aeon-state': widget.state }
+        : {}
+
+  const props: Record<string, unknown> = {
+    ...attrs,
+    className: widget.className,
+    role: widget.role,
+    disabled: widget.disabled || undefined,
+    type: widget.tag === 'button' ? widget.buttonType ?? 'button' : undefined,
+    onSubmit:
+      widget.tag === 'form' && widget.onSubmit
+        ? (event: { preventDefault(): void }) => widget.onSubmit?.(event)
+        : undefined,
+    onClick: widget.onClick,
+  }
+
+  return createElement(
+    widget.tag,
+    props,
+    ...widget.children.map((child, index) =>
+      createElement(Fragment, { key: index }, interpret(child, hosts)),
+    ),
+  )
+}

package/packages/tree/src/totality.ts

@@ -0,0 +1,20 @@
+import type { Widget } from './widget.js'
+
+/** Every `data-aeon-state` token a tree would project. */
+export function widgetStates(widget: Widget): string[] {
+  if (widget.type !== 'el') return []
+  const own = widget.state ? [widget.state] : []
+  return [...own, ...widget.children.flatMap(widgetStates)]
+}
+
+/**
+ * States the chart names that the projection never puts on the tree.
+ * Totality (PHILOSOPHY.md §2): if the machine has the state, the face for
+ * that state must carry it. A missing name is a face the UI forgot.
+ */
+export function uncoveredStates(
+  states: readonly string[],
+  project: (state: string) => Widget,
+): string[] {
+  return states.filter((state) => !widgetStates(project(state)).includes(state))
+}

package/packages/tree/src/widget.ts

@@ -0,0 +1,31 @@
+/**
+ * A widget is configuration, the way a Flutter `Widget` is: immutable data
+ * describing one face of a chart. It holds no lifecycle. The only state it
+ * may name is a snapshot already produced by a machine (`data-aeon-state`).
+ *
+ * Callbacks are event bindings (what to send), not state. There is no
+ * equivalent of `StatefulWidget` or `setState` — a second copy of the chart
+ * living in the tree would be the boolean twin this layer exists to remove.
+ */
+export type Widget =
+  | { type: 'text'; text: string }
+  | { type: 'host'; id: string }
+  | {
+      type: 'el'
+      tag: 'div' | 'form' | 'button' | 'p' | 'span'
+      scope?: string
+      part?: string
+      /** Chart snapshot token. Projected onto `data-aeon-state`. */
+      state?: string
+      className?: string
+      buttonType?: 'button' | 'submit'
+      disabled?: boolean
+      role?: string
+      onSubmit?: (event: { preventDefault(): void }) => void
+      onClick?: () => void
+      children: Widget[]
+    }
+
+export const text = (value: string): Widget => ({ type: 'text', text: value })
+
+export const host = (id: string): Widget => ({ type: 'host', id })

package/packages/tree/tsconfig.json

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

package/packages/tree/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['src/**/*.test.ts'],
+  },
+})

package/scripts/link-scoped-packages.mjs

@@ -0,0 +1,206 @@
+/**
+ * Materialize `node_modules/@aeon-ui/*` → `aeon-ui-engine/packages/*`
+ * so Next.js / Vite / Node can resolve scoped imports without bundler aliases.
+ *
+ * Runs as `aeon-ui-engine` postinstall (uses INIT_CWD) or via `npx aeon-ui link`.
+ *
+ * @example
+ * node ./scripts/link-scoped-packages.mjs
+ * node ./scripts/link-scoped-packages.mjs --cwd /path/to/app
+ */
+
+import { createRequire } from 'node:module'
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readlinkSync,
+  realpathSync,
+  rmSync,
+  symlinkSync,
+} from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url))
+
+/** Packages exposed under `@aeon-ui/<name>` for consumers. */
+export const SCOPED_PACKAGES = [
+  'core',
+  'primitives',
+  'react',
+  'ui',
+  'panda',
+  'schemas',
+  'surface',
+  'vue',
+  'solid',
+  'svelte',
+]
+
+/**
+ * Absolute path to the `aeon-ui-engine` package root (npm install or monorepo).
+ */
+export function resolveEngineRoot(opts = {}) {
+  if (opts.engineRoot) return path.resolve(opts.engineRoot)
+  if (process.env.AEON_UI_ROOT) return path.resolve(process.env.AEON_UI_ROOT)
+
+  try {
+    const require = createRequire(import.meta.url)
+    return path.dirname(require.resolve('aeon-ui-engine/package.json'))
+  } catch {
+    // Running from the monorepo checkout (this file lives in scripts/).
+    return path.resolve(scriptDir, '..')
+  }
+}
+
+/**
+ * Consumer `node_modules` where `@aeon-ui/*` should appear.
+ * Prefer INIT_CWD (npm/pnpm/yarn set this to the install project).
+ */
+export function resolveTargetNodeModules(opts = {}) {
+  if (opts.nodeModules) return path.resolve(opts.nodeModules)
+  if (opts.cwd) return path.join(path.resolve(opts.cwd), 'node_modules')
+
+  // Prefer INIT_CWD (npm/pnpm/yarn set this to the install project).
+  // Skip when postinstall runs inside the engine package itself during a
+  // monorepo install — workspace already provides @aeon-ui/*.
+  if (process.env.INIT_CWD) {
+    const initCwd = path.resolve(process.env.INIT_CWD)
+    const engineRoot = resolveEngineRoot(opts)
+    if (initCwd === engineRoot) {
+      return path.join(engineRoot, 'node_modules')
+    }
+    return path.join(initCwd, 'node_modules')
+  }
+
+  const engineRoot = resolveEngineRoot(opts)
+  // Installed as dependency: …/node_modules/aeon-ui-engine
+  const parent = path.dirname(engineRoot)
+  if (path.basename(parent) === 'node_modules') {
+    return parent
+  }
+
+  // Monorepo / direct run: link into engine's own node_modules
+  return path.join(engineRoot, 'node_modules')
+}
+
+function isSymlink(p) {
+  try {
+    return lstatSync(p).isSymbolicLink()
+  } catch {
+    return false
+  }
+}
+
+function sameTarget(linkPath, absTarget) {
+  try {
+    const current = readlinkSync(linkPath)
+    const resolved = path.isAbsolute(current)
+      ? path.normalize(current)
+      : path.resolve(path.dirname(linkPath), current)
+    if (resolved === absTarget) return true
+  } catch {
+    /* not a symlink or unreadable */
+  }
+  try {
+    return realpathSync(linkPath) === realpathSync(absTarget)
+  } catch {
+    return false
+  }
+}
+
+/**
+ * @param {{ cwd?: string, engineRoot?: string, nodeModules?: string, quiet?: boolean, force?: boolean }} [opts]
+ * @returns {{ linked: string[], skipped: string[], missing: string[], targetNodeModules: string, engineRoot: string }}
+ */
+export function linkScopedPackages(opts = {}) {
+  const quiet = opts.quiet ?? false
+  const force = opts.force ?? false
+  const engineRoot = resolveEngineRoot(opts)
+  const targetNodeModules = resolveTargetNodeModules({ ...opts, engineRoot })
+  const scopeDir = path.join(targetNodeModules, '@aeon-ui')
+  const packagesRoot = path.join(engineRoot, 'packages')
+
+  const linked = []
+  const skipped = []
+  const missing = []
+
+  mkdirSync(scopeDir, { recursive: true })
+
+  for (const name of SCOPED_PACKAGES) {
+    const absTarget = path.join(packagesRoot, name)
+    if (!existsSync(absTarget)) {
+      missing.push(name)
+      continue
+    }
+
+    const linkPath = path.join(scopeDir, name)
+
+    if (existsSync(linkPath) || isSymlink(linkPath)) {
+      if (sameTarget(linkPath, absTarget)) {
+        skipped.push(name)
+        continue
+      }
+      // Do not clobber pnpm/npm workspace links unless --force
+      if (!force) {
+        skipped.push(name)
+        continue
+      }
+      rmSync(linkPath, { recursive: true, force: true })
+    }
+
+    const type = process.platform === 'win32' ? 'junction' : 'dir'
+    symlinkSync(absTarget, linkPath, type)
+    linked.push(name)
+  }
+
+  if (!quiet) {
+    const rel = (n) => `@aeon-ui/${n}`
+    for (const n of linked) console.log(`  link ${rel(n)} → packages/${n}`)
+    for (const n of skipped) console.log(`  skip ${rel(n)} (already present)`)
+    for (const n of missing) console.log(`  miss ${rel(n)} (not in engine)`)
+    if (linked.length === 0 && skipped.length > 0) {
+      console.log(`aeon-ui link: ${skipped.length} package(s) already present in ${targetNodeModules}`)
+    } else if (linked.length > 0) {
+      console.log(`aeon-ui link: linked ${linked.length} package(s) into ${targetNodeModules}`)
+    }
+  }
+
+  return { linked, skipped, missing, targetNodeModules, engineRoot }
+}
+
+function parseArgs(argv) {
+  const opts = {}
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--cwd' && argv[i + 1]) {
+      opts.cwd = argv[++i]
+    } else if (a === '--engine-root' && argv[i + 1]) {
+      opts.engineRoot = argv[++i]
+    } else if (a === '--quiet' || a === '-q') {
+      opts.quiet = true
+    } else if (a === '--force' || a === '-f') {
+      opts.force = true
+    }
+  }
+  return opts
+}
+
+const isMain = (() => {
+  if (!process.argv[1]) return false
+  try {
+    return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1])
+  } catch {
+    return path.resolve(fileURLToPath(import.meta.url)) === path.resolve(process.argv[1])
+  }
+})()
+
+if (isMain) {
+  try {
+    linkScopedPackages(parseArgs(process.argv.slice(2)))
+  } catch (err) {
+    console.error('aeon-ui link failed:', err instanceof Error ? err.message : err)
+    process.exitCode = 1
+  }
+}

package/scripts/vite-aliases.mjs

@@ -1,19 +1,17 @@
 /**
- * Vite + TypeScript wiring for apps that install `aeon-ui-engine` from npm.
+ * Vite helpers for apps that install `aeon-ui-engine` from npm.
+ *
+ * Scoped `@aeon-ui/*` imports resolve via postinstall linking
+ * (`aeon-ui-engine/link` / `npx aeon-ui link`). This plugin is optional —
+ * it still helps with optimizeDeps and monorepo `packagesRoot`.
  *
  * @example
- * // vite.config.ts — one call, done
+ * // vite.config.ts — optional
  * import { aeonUiVitePlugin } from 'aeon-ui-engine/vite'
  *
  * export default defineConfig({
  *   plugins: [react(), aeonUiVitePlugin()],
  * })
- *
- * // tsconfig.json — spread the base config
- * {
- *   "extends": "aeon-ui-engine/tsconfig",
- *   "compilerOptions": { "jsx": "react-jsx" }
- * }
  */
 import { createRequire } from 'node:module'
 import path from 'node:path'
@@ -101,6 +99,7 @@ export function aeonUiViteAliases(opts = {}) {
     { 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/schemas', replacement: path.join(packages, 'schemas/src/index.ts') },
+    { find: '@aeon-ui/tree', replacement: path.join(packages, 'tree/src/index.ts') },
     { find: '@aeon-ui/panda', replacement: path.join(packages, 'panda') },
   ]
 }
@@ -122,6 +121,7 @@ export function aeonUiOptimizeDeps(opts = {}) {
           '@aeon-ui/primitives',
           '@aeon-ui/react',
           '@aeon-ui/ui',
+          '@aeon-ui/tree',
           '@aeon-ui/panda/styled-system/css',
           '@aeon-ui/panda/styled-system/recipes',
           ...(opts.exclude ?? []),
@@ -142,6 +142,7 @@ export function aeonUiTsconfigPaths(opts = {}) {
     '@aeon-ui/react': [`${prefix}/react/src/index.ts`],
     '@aeon-ui/ui': [`${prefix}/ui/src/index.ts`],
     '@aeon-ui/surface': [`${prefix}/surface/src/index.ts`],
+    '@aeon-ui/tree': [`${prefix}/tree/src/index.ts`],
     '@aeon-ui/panda/styled-system/css': [`${prefix}/panda/styled-system/css/index.d.ts`],
     '@aeon-ui/panda/styled-system/recipes': [`${prefix}/panda/styled-system/recipes/index.d.ts`],
   }