aeon-ui-engine 1.0.3 → 1.1.0

package/packages/react/src/sticky-bar/index.tsx

@@ -0,0 +1,135 @@
+import { barAnatomy, partAttrs, scopeAttrs } from '@aeon-ui/core'
+import { stickyBarMachine, type StickyBarState } from '@aeon-ui/primitives'
+import {
+  createContext,
+  forwardRef,
+  useContext,
+  useMemo,
+  type CSSProperties,
+  type HTMLAttributes,
+  type ReactNode,
+} from 'react'
+import { useAeonMachine } from '../hooks/use-aeon-machine.js'
+import { mergeProps } from '../utils/merge-props.js'
+
+interface StickyBarContextValue {
+  state: StickyBarState
+  offsetPx: number
+  send: ReturnType<typeof useAeonMachine<typeof stickyBarMachine>>[1]
+}
+
+const StickyBarCtx = createContext<StickyBarContextValue | null>(null)
+
+export function useStickyBarContext() {
+  const ctx = useContext(StickyBarCtx)
+  if (!ctx) throw new Error('StickyBar parts must be used within StickyBar.Root')
+  return ctx
+}
+
+export interface StickyBarRootProps extends HTMLAttributes<HTMLElement> {
+  as?: 'header' | 'nav' | 'footer' | 'div'
+  /** Placement — top | bottom | inline (CSS contract). */
+  placement?: 'top' | 'bottom' | 'inline'
+  /** Initial machine state. */
+  defaultState?: StickyBarState
+  children?: ReactNode
+}
+
+const Root = forwardRef<HTMLElement, StickyBarRootProps>(function StickyBarRoot(
+  {
+    /* Default div — AppShell.Header is already the landmark; nested <header> is invalid
+       HTML and browsers auto-close the outer header (0-height), so the bar covers content. */
+    as: Tag = 'div',
+    placement = 'top',
+    defaultState = 'floating',
+    children,
+    style,
+    ...rest
+  },
+  ref,
+) {
+  const [snapshot, send] = useAeonMachine(stickyBarMachine, {
+    input: { initial: defaultState },
+  })
+  const state = snapshot.value as StickyBarState
+  const offsetPx = snapshot.context.offsetPx
+  const value = useMemo(() => ({ state, offsetPx, send }), [state, offsetPx, send])
+
+  if (state === 'hidden') return null
+
+  const stickyStyle: CSSProperties = {
+    ...(typeof style === 'object' && style ? style : {}),
+    ...(offsetPx > 0 ? ({ ['--aeon-bar-offset' as string]: `${offsetPx}px` } as CSSProperties) : {}),
+  }
+
+  return (
+    <StickyBarCtx.Provider value={value}>
+      <Tag
+        ref={ref as never}
+        data-aeon-placement={placement}
+        style={stickyStyle}
+        {...mergeProps(scopeAttrs(barAnatomy.scope, barAnatomy.root, { state }), rest)}
+      >
+        {children}
+      </Tag>
+    </StickyBarCtx.Provider>
+  )
+})
+
+type Zone = 'leading' | 'center' | 'trailing'
+
+const Zone = forwardRef<
+  HTMLDivElement,
+  HTMLAttributes<HTMLDivElement> & { zone: Zone }
+>(function StickyBarZone({ zone, ...rest }, ref) {
+  const { state } = useStickyBarContext()
+  return (
+    <div
+      ref={ref}
+      {...mergeProps(partAttrs(barAnatomy.scope, zone, { state }), rest)}
+    />
+  )
+})
+
+const Leading = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(
+  function StickyBarLeading(props, ref) {
+    return <Zone ref={ref} zone="leading" {...props} />
+  },
+)
+const Center = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(
+  function StickyBarCenter(props, ref) {
+    return <Zone ref={ref} zone="center" {...props} />
+  },
+)
+const Trailing = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(
+  function StickyBarTrailing(props, ref) {
+    return <Zone ref={ref} zone="trailing" {...props} />
+  },
+)
+
+const Seam = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(function StickyBarSeam(
+  props,
+  ref,
+) {
+  const { state } = useStickyBarContext()
+  return (
+    <div
+      ref={ref}
+      aria-hidden
+      {...mergeProps(partAttrs(barAnatomy.scope, barAnatomy.seam, { state }), props)}
+    />
+  )
+})
+
+/**
+ * StickyBar — sticky/fixed chrome band with machine totality.
+ * States: floating | docked | collapsed | hidden
+ * Zones reuse bar anatomy (leading / center / trailing / seam).
+ */
+export const StickyBar = {
+  Root,
+  Leading,
+  Center,
+  Trailing,
+  Seam,
+}

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

@@ -101,7 +101,13 @@ const Root = forwardRef<HTMLLabelElement, SwitchRootProps>(function SwitchRoot(
           rest as ButtonHTMLAttributes<HTMLLabelElement>,
         )}
       >
-        {children}
+        {children ?? (
+          <>
+            <Control>
+              <Thumb />
+            </Control>
+          </>
+        )}
       </label>
     </SwitchCtx.Provider>
   )

package/packages/react/src/theme-switcher/index.tsx

@@ -0,0 +1,227 @@
+import { partAttrs, scopeAttrs, themeSwitcherAnatomy } from '@aeon-ui/core'
+import {
+  applyAeonTheme,
+  initAeonTheme,
+  type AeonColorMode,
+} from '@aeon-ui/core'
+import {
+  createContext,
+  forwardRef,
+  type HTMLAttributes,
+  useContext,
+  useLayoutEffect,
+  useState,
+} from 'react'
+import { mergeProps } from '../utils/merge-props.js'
+
+/* ------------------------------------------------------------------ */
+/*  Types                                                              */
+/* ------------------------------------------------------------------ */
+
+export interface ThemeSwitcherRootProps extends HTMLAttributes<HTMLDivElement> {
+  /** Initial theme — overridden by localStorage / system preference. */
+  defaultTheme?: string
+  /** Initial mode — overridden by localStorage / system preference. */
+  defaultMode?: AeonColorMode
+  /** Called when theme or mode changes. */
+  onThemeChange?: (themeId: string, mode: AeonColorMode) => void
+}
+
+export interface ThemeSwitcherModesProps extends HTMLAttributes<HTMLDivElement> {}
+
+export interface ThemeSwitcherModeBtnProps extends HTMLAttributes<HTMLButtonElement> {
+  mode: AeonColorMode
+  active: boolean
+}
+
+export interface ThemeSwitcherThemeSelectProps extends HTMLAttributes<HTMLDivElement> {}
+
+/* ------------------------------------------------------------------ */
+/*  Root                                                               */
+/* ------------------------------------------------------------------ */
+
+const Root = forwardRef<HTMLDivElement, ThemeSwitcherRootProps>(
+  function ThemeSwitcherRoot(
+    { defaultTheme, defaultMode, onThemeChange, children, ...rest },
+    ref,
+  ) {
+    const [themeId, setThemeId] = useState(defaultTheme ?? 'default')
+    const [mode, setMode] = useState<AeonColorMode>(defaultMode ?? 'dark')
+
+    useLayoutEffect(() => {
+      const { themeId: t, mode: m } = initAeonTheme()
+      setThemeId(t)
+      setMode(m)
+    }, [])
+
+    const handleThemeChange = (next: string) => {
+      setThemeId(next)
+      applyAeonTheme(next, mode)
+      onThemeChange?.(next, mode)
+    }
+
+    const handleModeChange = (next: AeonColorMode) => {
+      setMode(next)
+      applyAeonTheme(themeId, next)
+      onThemeChange?.(themeId, next)
+    }
+
+    return (
+      <div
+        ref={ref}
+        {...mergeProps(
+          scopeAttrs(themeSwitcherAnatomy.scope, themeSwitcherAnatomy.root),
+          rest,
+        )}
+      >
+        <ThemeSwitcherContext.Provider
+          value={{ themeId, mode, handleThemeChange, handleModeChange }}
+        >
+          {children}
+        </ThemeSwitcherContext.Provider>
+      </div>
+    )
+  },
+)
+
+/* ------------------------------------------------------------------ */
+/*  Context                                                            */
+/* ------------------------------------------------------------------ */
+
+interface ThemeSwitcherContextValue {
+  themeId: string
+  mode: AeonColorMode
+  handleThemeChange: (id: string) => void
+  handleModeChange: (mode: AeonColorMode) => void
+}
+
+const ThemeSwitcherContext = createContext<ThemeSwitcherContextValue | null>(null)
+
+function useThemeSwitcher() {
+  const ctx = useContext(ThemeSwitcherContext)
+  if (!ctx) throw new Error('ThemeSwitcher parts must be used inside <ThemeSwitcher.Root>')
+  return ctx
+}
+
+/* ------------------------------------------------------------------ */
+/*  Modes (light/dark button group)                                    */
+/* ------------------------------------------------------------------ */
+
+const Modes = forwardRef<HTMLDivElement, ThemeSwitcherModesProps>(
+  function ThemeSwitcherModes(props, ref) {
+    return (
+      <div
+        ref={ref}
+        role="group"
+        aria-label="Color mode"
+        {...mergeProps(
+          partAttrs(themeSwitcherAnatomy.scope, themeSwitcherAnatomy.modes),
+          props,
+        )}
+      />
+    )
+  },
+)
+
+/* ------------------------------------------------------------------ */
+/*  Mode button                                                        */
+/* ------------------------------------------------------------------ */
+
+const ModeBtn = forwardRef<HTMLButtonElement, ThemeSwitcherModeBtnProps>(
+  function ThemeSwitcherModeBtn({ mode, active, ...rest }, ref) {
+    const { handleModeChange } = useThemeSwitcher()
+    return (
+      <button
+        ref={ref}
+        type="button"
+        aria-pressed={active}
+        data-active={active ? 'true' : undefined}
+        {...mergeProps(
+          partAttrs(themeSwitcherAnatomy.scope, themeSwitcherAnatomy.modeBtn),
+          rest,
+        )}
+        onClick={(e) => {
+          handleModeChange(mode)
+          rest.onClick?.(e)
+        }}
+      >
+        {rest.children ?? (mode === 'light' ? 'Light' : 'Dark')}
+      </button>
+    )
+  },
+)
+
+/* ------------------------------------------------------------------ */
+/*  Theme select wrapper                                               */
+/* ------------------------------------------------------------------ */
+
+const ThemeSelect = forwardRef<HTMLDivElement, ThemeSwitcherThemeSelectProps>(
+  function ThemeSwitcherThemeSelect({ children, ...rest }, ref) {
+    return (
+      <div
+        ref={ref}
+        {...mergeProps(
+          partAttrs(themeSwitcherAnatomy.scope, themeSwitcherAnatomy.themeSelect),
+          rest,
+        )}
+      >
+        {children}
+      </div>
+    )
+  },
+)
+
+/* ------------------------------------------------------------------ */
+/*  Theme trigger (displays current theme label)                        */
+/* ------------------------------------------------------------------ */
+
+const ThemeTrigger = forwardRef<HTMLButtonElement, HTMLAttributes<HTMLButtonElement>>(
+  function ThemeSwitcherThemeTrigger(props, ref) {
+    const { themeId } = useThemeSwitcher()
+    return (
+      <button
+        ref={ref}
+        type="button"
+        aria-label={`Theme preset: ${themeId}`}
+        {...mergeProps(
+          partAttrs(themeSwitcherAnatomy.scope, themeSwitcherAnatomy.themeTrigger),
+          props,
+        )}
+      >
+        {props.children ?? themeId}
+      </button>
+    )
+  },
+)
+
+/* ------------------------------------------------------------------ */
+/*  Public API                                                         */
+/* ------------------------------------------------------------------ */
+
+/**
+ * ThemeSwitcher — headless compound component for theme + mode control.
+ *
+ * Uses `initAeonTheme()` on mount to read localStorage / system preference.
+ * All state changes call `applyAeonTheme()` to update `<html>` dataset attrs.
+ *
+ * @example
+ * <ThemeSwitcher.Root>
+ *   <ThemeSwitcher.Modes>
+ *     <ThemeSwitcher.ModeBtn mode="light" active={mode === 'light'} />
+ *     <ThemeSwitcher.ModeBtn mode="dark" active={mode === 'dark'} />
+ *   </ThemeSwitcher.Modes>
+ *   <ThemeSwitcher.ThemeSelect>
+ *     <ThemeSwitcher.ThemeTrigger />
+ *   </ThemeSwitcher.ThemeSelect>
+ * </ThemeSwitcher.Root>
+ */
+export const ThemeSwitcher = {
+  Root,
+  Modes,
+  ModeBtn,
+  ThemeSelect,
+  ThemeTrigger,
+}
+
+/** Re-export theme types for convenience. */
+export type { AeonColorMode as AeonMode }

package/packages/react/src/thread/index.tsx

@@ -0,0 +1,95 @@
+import { partAttrs, scopeAttrs, threadAnatomy } from '@aeon-ui/core'
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react'
+import { mergeProps } from '../utils/merge-props.js'
+
+export type ThreadMessageState = 'mine' | 'theirs' | 'pending' | 'failed'
+
+export interface ThreadRootProps extends HTMLAttributes<HTMLElement> {
+  children?: ReactNode
+}
+
+/**
+ * Thread — message stream. Item `state` projects mine | theirs | pending | failed.
+ */
+const Root = forwardRef<HTMLElement, ThreadRootProps>(function ThreadRoot(
+  { children, ...rest },
+  ref,
+) {
+  return (
+    <div
+      ref={ref as never}
+      {...mergeProps(scopeAttrs(threadAnatomy.scope, threadAnatomy.root), rest)}
+    >
+      {children}
+    </div>
+  )
+})
+
+const List = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(function ThreadList(
+  props,
+  ref,
+) {
+  return (
+    <div
+      ref={ref}
+      role="log"
+      aria-live="polite"
+      {...mergeProps(partAttrs(threadAnatomy.scope, threadAnatomy.list), props)}
+    />
+  )
+})
+
+export interface ThreadItemProps extends HTMLAttributes<HTMLDivElement> {
+  state?: ThreadMessageState | `${ThreadMessageState} ${string}`
+}
+
+const Item = forwardRef<HTMLDivElement, ThreadItemProps>(function ThreadItem(
+  { state = 'theirs', ...rest },
+  ref,
+) {
+  return (
+    <div
+      ref={ref}
+      {...mergeProps(partAttrs(threadAnatomy.scope, threadAnatomy.item, { state }), rest)}
+    />
+  )
+})
+
+const Bubble = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(function ThreadBubble(
+  props,
+  ref,
+) {
+  return (
+    <div
+      ref={ref}
+      {...mergeProps(partAttrs(threadAnatomy.scope, threadAnatomy.bubble), props)}
+    />
+  )
+})
+
+const Meta = forwardRef<HTMLSpanElement, HTMLAttributes<HTMLSpanElement>>(function ThreadMeta(
+  props,
+  ref,
+) {
+  return (
+    <span ref={ref} {...mergeProps(partAttrs(threadAnatomy.scope, threadAnatomy.meta), props)} />
+  )
+})
+
+const Day = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(function ThreadDay(
+  props,
+  ref,
+) {
+  return (
+    <div ref={ref} {...mergeProps(partAttrs(threadAnatomy.scope, threadAnatomy.day), props)} />
+  )
+})
+
+export const Thread = {
+  Root,
+  List,
+  Item,
+  Bubble,
+  Meta,
+  Day,
+}

package/packages/react/src/toast/primitives.tsx

@@ -105,7 +105,7 @@ export const CloseTrigger = forwardRef<HTMLButtonElement, ButtonHTMLAttributes<H
       <button
         ref={ref}
         type="button"
-        aria-label={typeof children === 'string' ? undefined : 'Dismiss'}
+        aria-label="Dismiss"
         {...mergeProps(
           partAttrs(toastAnatomy.scope, toastAnatomy.closeTrigger),
           {
@@ -117,7 +117,7 @@ export const CloseTrigger = forwardRef<HTMLButtonElement, ButtonHTMLAttributes<H
           rest,
         )}
       >
-        {children ?? 'Dismiss'}
+        {children ?? '\u00d7'}
       </button>
     )
   },

package/packages/react/src/tooltip/tooltip.test.tsx

@@ -4,14 +4,22 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { Tooltip } from './index.js'
 
 function mockPrefersHover(matches: boolean) {
+  if (!window.matchMedia) {
+    Object.defineProperty(window, 'matchMedia', {
+      writable: true,
+      value: vi.fn(),
+    })
+  }
   vi.spyOn(window, 'matchMedia').mockImplementation((query) => ({
     matches: query.includes('hover: hover') ? matches : false,
     media: query,
     onchange: null,
+    addListener: vi.fn(),
+    removeListener: vi.fn(),
     addEventListener: vi.fn(),
     removeEventListener: vi.fn(),
     dispatchEvent: vi.fn(),
-  }))
+  }) as unknown as MediaQueryList)
 }
 
 describe('Tooltip', () => {

package/packages/react/tsconfig.json

@@ -2,7 +2,8 @@
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
     "outDir": "dist",
-    "rootDir": "src"
+    "rootDir": "src",
+    "types": ["@testing-library/jest-dom/vitest"]
   },
   "include": ["src"]
 }

package/packages/schemas/README.md

@@ -0,0 +1,52 @@
+# @aeon-ui/schemas
+
+Deterministic **JSON Schemas**, **statechart → LLM prompts**, and **agent event bridges** for Aeon UI.
+
+## Install
+
+```bash
+npm install @aeon-ui/schemas
+npx aeon-ui init
+```
+
+## Statechart-as-a-prompt
+
+```ts
+import { createActor } from 'xstate'
+import { asyncMachine } from '@aeon-ui/primitives'
+import { aeonToSchema, aeonToPrompt, aeonSnapshotSchema, createAgentEventBridge } from '@aeon-ui/schemas'
+
+const schema = aeonToSchema(asyncMachine)
+// hierarchical tree + events — feed to tools / zod enums
+
+const actor = createActor(asyncMachine)
+actor.start()
+const prompt = aeonToPrompt(asyncMachine, actor.getSnapshot())
+const live = aeonSnapshotSchema(asyncMachine, actor.getSnapshot())
+// live.validEvents → only what the agent may send *now*
+
+const bridge = createAgentEventBridge(actor, {
+  map: {
+    AGENT_STREAM_START: 'FETCH',
+    AGENT_STREAM_ERROR: (e) =>
+      e.type === 'AGENT_STREAM_ERROR' ? { type: 'REJECT', error: e.error } : null,
+  },
+})
+bridge.push({ type: 'AGENT_STREAM_START' })
+```
+
+## Registry
+
+Runtime fetch (also mirrored on the demo at `/registry/`):
+
+- `https://aeon-ui.com/registry/catalog.json`
+- `https://aeon-ui.com/registry/components/button.json`
+- `https://aeon-ui.com/registry/machines/async.json`
+
+## Cookbook
+
+[Vercel AI SDK + streamUI](../../docs/cookbook/vercel-ai-sdk.md)
+
+## Principle
+
+**UI = f(state)** — if it is not on the chart / in `validEvents`, do not send it.