aeon-ui-engine 1.5.1 → 1.8.0

package/packages/tree/node_modules/.bin/vitest

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/Users/brandoncryderman/AeonUI/node_modules/.pnpm/vitest@4.1.8_@types+node@22.19.19_jsdom@29.1.1_vite@8.0.16_@types+node@22.19.19_esbuild@0.28.0_jiti@2.7.0_tsx@4.22.3_/node_modules/vitest/node_modules:/Users/brandoncryderman/AeonUI/node_modules/.pnpm/vitest@4.1.8_@types+node@22.19.19_jsdom@29.1.1_vite@8.0.16_@types+node@22.19.19_esbuild@0.28.0_jiti@2.7.0_tsx@4.22.3_/node_modules:/Users/brandoncryderman/AeonUI/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/Users/brandoncryderman/AeonUI/node_modules/.pnpm/vitest@4.1.8_@types+node@22.19.19_jsdom@29.1.1_vite@8.0.16_@types+node@22.19.19_esbuild@0.28.0_jiti@2.7.0_tsx@4.22.3_/node_modules/vitest/node_modules:/Users/brandoncryderman/AeonUI/node_modules/.pnpm/vitest@4.1.8_@types+node@22.19.19_jsdom@29.1.1_vite@8.0.16_@types+node@22.19.19_esbuild@0.28.0_jiti@2.7.0_tsx@4.22.3_/node_modules:/Users/brandoncryderman/AeonUI/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../vitest/vitest.mjs" "$@"
+else
+  exec node  "$basedir/../vitest/vitest.mjs" "$@"
+fi

package/packages/tree/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json

@@ -0,0 +1 @@
+{"version":"4.1.8","results":[[":src/exclusive-action.test.ts",{"duration":2.708500000000001,"failed":false}]]}

package/packages/tree/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@aeon-ui/tree",
+  "version": "0.1.0",
+  "description": "Widget trees: UI as data projected from a statechart snapshot. Flutter's Widget layer, Aeon's anatomy, no local state.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GenericCPU/aeon-ui.git",
+    "directory": "packages/tree"
+  },
+  "publishConfig": { "access": "public" },
+  "files": ["dist", "README.md"],
+  "keywords": ["aeon-ui", "statechart", "widget", "xstate"],
+  "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 react",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@aeon-ui/core": "workspace:*"
+  },
+  "peerDependencies": {
+    "react": "^18 || ^19"
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.2",
+    "react": "^19.1.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3",
+    "vitest": "^4.1.8"
+  }
+}

package/packages/tree/src/exclusive-action.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest'
+import { exclusiveActionWidget, EXCLUSIVE_ACTION_STATES } from './exclusive-action.js'
+import { uncoveredStates, widgetStates } from './totality.js'
+import { host } from './widget.js'
+
+const project = (state: string) =>
+  exclusiveActionWidget({
+    scope: 'example',
+    part: 'form',
+    state,
+    busy: state === 'busy' || state === 'confirming',
+    error: state === 'failure' ? 'nope' : null,
+    body: host('body'),
+    idleLabel: 'Save',
+    pendingLabel: 'Saving…',
+    onSubmit: () => {},
+    confirm: state === 'confirming',
+  })
+
+describe('exclusiveActionWidget', () => {
+  it('covers every state of the chart', () => {
+    expect(uncoveredStates(EXCLUSIVE_ACTION_STATES, project)).toEqual([])
+  })
+
+  it('shows the failure copy only on failure', () => {
+    expect(widgetStates(project('idle'))).not.toContain('failure')
+    const failure = project('failure')
+    const error = failure.type === 'el' && failure.children.find((c) => c.type === 'el' && c.part === 'error')
+    expect(error && error.type === 'el' && error.children[0]).toEqual({ type: 'text', text: 'nope' })
+  })
+
+  it('mounts the confirm host only while confirming', () => {
+    const confirming = project('confirming')
+    const idle = project('idle')
+    const hasConfirm = (tree: ReturnType<typeof project>) =>
+      tree.type === 'el' && tree.children.some((c) => c.type === 'host' && c.id === 'confirm')
+    expect(hasConfirm(confirming)).toBe(true)
+    expect(hasConfirm(idle)).toBe(false)
+  })
+
+  it('labels the primary from busy, and refuses a second click', () => {
+    const busy = project('busy')
+    const primary =
+      busy.type === 'el'
+        ? busy.children
+            .flatMap((c) => (c.type === 'el' ? c.children : []))
+            .find((c) => c.type === 'el' && c.part === 'primary')
+        : undefined
+    expect(primary && primary.type === 'el' && primary.disabled).toBe(true)
+    expect(primary && primary.type === 'el' && primary.children).toEqual([
+      { type: 'text', text: 'Saving…' },
+    ])
+  })
+})

package/packages/tree/src/exclusive-action.ts

@@ -0,0 +1,104 @@
+import { host, text, type Widget } from './widget.js'
+
+/**
+ * The chart every "click, maybe confirm, await, succeed or fail" region
+ * shares. One region, four faces — not a `busy` boolean beside the markup.
+ */
+export const EXCLUSIVE_ACTION_STATES = ['idle', 'confirming', 'busy', 'failure'] as const
+
+export type ExclusiveActionState = (typeof EXCLUSIVE_ACTION_STATES)[number]
+
+export type ExclusiveActionInput = {
+  scope: string
+  part: string
+  /** Active snapshot token, usually `stateToAttr(snapshot.value)`. */
+  state: string
+  busy: boolean
+  error: string | null
+  className?: string
+  tag?: 'form' | 'div'
+  /** Panel-specific fields. A host, so the tree stays generic. */
+  body: Widget
+  idleLabel: string
+  pendingLabel: string
+  primaryClassName?: string
+  primaryDisabled?: boolean
+  onSubmit?: (event: { preventDefault(): void }) => void
+  secondary?: {
+    label: string
+    className?: string
+    disabled?: boolean
+    onClick: () => void
+  }
+  actionsClassName?: string
+  /** When set, the `confirm` host is mounted. The app renders its Prompt there. */
+  confirm?: boolean
+}
+
+/**
+ * One widget for an exclusive mutation. The root carries the chart state;
+ * the primary label and the disabled set are functions of `busy`, and the
+ * failure copy is a child that exists only when `error` is set.
+ */
+export function exclusiveActionWidget(input: ExclusiveActionInput): Widget {
+  const children: Widget[] = [input.body]
+
+  if (input.error) {
+    children.push({
+      type: 'el',
+      tag: 'p',
+      part: 'error',
+      className: 'error',
+      role: 'alert',
+      children: [text(input.error)],
+    })
+  }
+
+  const actions: Widget[] = [
+    {
+      type: 'el',
+      tag: 'button',
+      part: 'primary',
+      buttonType: input.tag === 'div' ? 'button' : 'submit',
+      disabled: input.busy || input.primaryDisabled,
+      className: input.primaryClassName,
+      onClick: input.tag === 'div' ? () => input.onSubmit?.({ preventDefault() {} }) : undefined,
+      children: [text(input.busy ? input.pendingLabel : input.idleLabel)],
+    },
+  ]
+
+  if (input.secondary) {
+    actions.push({
+      type: 'el',
+      tag: 'button',
+      part: 'secondary',
+      buttonType: 'button',
+      disabled: input.busy || input.secondary.disabled,
+      className: input.secondary.className,
+      onClick: input.secondary.onClick,
+      children: [text(input.secondary.label)],
+    })
+  }
+
+  children.push({
+    type: 'el',
+    tag: 'div',
+    part: 'actions',
+    className: input.actionsClassName,
+    state: input.state,
+    children: actions,
+  })
+
+  if (input.confirm) children.push(host('confirm'))
+
+  return {
+    type: 'el',
+    tag: input.tag ?? 'form',
+    scope: input.scope,
+    part: input.part,
+    state: input.state,
+    className: input.className,
+    onSubmit: input.tag === 'div' ? undefined : input.onSubmit,
+    children,
+  }
+}

package/packages/tree/src/index.ts

@@ -0,0 +1,7 @@
+export { exclusiveActionWidget, EXCLUSIVE_ACTION_STATES } from './exclusive-action.js'
+export type { ExclusiveActionInput, ExclusiveActionState } from './exclusive-action.js'
+export { interpret } from './interpret.js'
+export type { WidgetHosts } from './interpret.js'
+export { uncoveredStates, widgetStates } from './totality.js'
+export { host, text } from './widget.js'
+export type { Widget } from './widget.js'

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/vite-aliases.mjs

@@ -99,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') },
   ]
 }
@@ -120,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 ?? []),
@@ -140,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`],
   }