@elizaos/app-core 2.0.0-alpha.37

package/src/config/ui-spec.ts

@@ -0,0 +1,256 @@
+/**
+ * ui-spec.ts — TypeScript types for the json-render declarative UI spec.
+ *
+ * A UiSpec describes a tree of UI components that can be rendered
+ * from a JSON declaration. This is the full json-render component model.
+ *
+ * Structure:
+ *   { root: "main", elements: { [id]: UiElement }, state: { ... } }
+ *
+ * Each element has a type, props, optional children (IDs), event bindings,
+ * conditional visibility, validation, and repeat/list support.
+ */
+
+// ── Dynamic value references ────────────────────────────────────────
+
+/** A value that can be either a literal or a path reference. */
+export type DynamicProp<T = string> = T | { $path: string };
+
+/** Conditional expression for dynamic prop resolution. */
+export interface CondExpr {
+  $cond: {
+    eq?: [unknown, unknown];
+    neq?: [unknown, unknown];
+    gt?: [unknown, unknown];
+    lt?: [unknown, unknown];
+    gte?: [unknown, unknown];
+    lte?: [unknown, unknown];
+    truthy?: unknown;
+    falsy?: unknown;
+    path?: string;
+  };
+  $then: unknown;
+  $else: unknown;
+}
+
+// ── Visibility ──────────────────────────────────────────────────────
+
+export type VisibilityOperator = "eq" | "ne" | "gt" | "gte" | "lt" | "lte";
+
+/** Path-based visibility condition. */
+export interface PathVisibility {
+  path: string;
+  operator: VisibilityOperator;
+  value: unknown;
+}
+
+/** Auth-based visibility condition. */
+export interface AuthVisibility {
+  auth: "signedIn" | "signedOut" | "admin" | string;
+}
+
+/** Logical combinators for complex visibility. */
+export interface AndVisibility {
+  and: VisibilityCondition[];
+}
+export interface OrVisibility {
+  or: VisibilityCondition[];
+}
+export interface NotVisibility {
+  not: VisibilityCondition;
+}
+
+export type VisibilityCondition =
+  | PathVisibility
+  | AuthVisibility
+  | AndVisibility
+  | OrVisibility
+  | NotVisibility;
+
+// ── Validation ──────────────────────────────────────────────────────
+
+/** Built-in validator function names. */
+export type BuiltinValidator =
+  | "required"
+  | "email"
+  | "minLength"
+  | "maxLength"
+  | "pattern"
+  | "min"
+  | "max";
+
+/** A single validation check on a field. */
+export interface ValidationCheck {
+  fn: string;
+  args?: Record<string, unknown>;
+  message: string;
+}
+
+/** Validation configuration for a form element. */
+export interface ValidationConfig {
+  checks: ValidationCheck[];
+  validateOn?: "change" | "blur" | "submit";
+}
+
+// ── Event binding ───────────────────────────────────────────────────
+
+/** Action success/error handlers. */
+export interface ActionOnSuccess {
+  action: string;
+  params?: Record<string, unknown>;
+}
+
+export interface ActionOnError {
+  action: string;
+  params?: Record<string, unknown>;
+}
+
+/** Confirmation prompt before action execution. */
+export interface ActionConfirm {
+  title: string;
+  message?: string;
+  confirmLabel?: string;
+  cancelLabel?: string;
+}
+
+export interface UiAction {
+  action: string;
+  params?: Record<string, unknown>;
+  confirm?: ActionConfirm;
+  onSuccess?: ActionOnSuccess;
+  onError?: ActionOnError;
+}
+
+export type UiEventBindings = Record<string, UiAction>;
+
+// ── Repeat / list rendering ─────────────────────────────────────────
+
+export interface RepeatConfig {
+  path: string;
+  key: string;
+}
+
+// ── Element types ───────────────────────────────────────────────────
+
+export type UiComponentType =
+  // Layout
+  | "Stack"
+  | "Grid"
+  | "Card"
+  | "Separator"
+  // Typography
+  | "Heading"
+  | "Text"
+  // Form
+  | "Input"
+  | "Textarea"
+  | "Select"
+  | "Checkbox"
+  | "Radio"
+  | "Switch"
+  | "Slider"
+  | "Toggle"
+  | "ToggleGroup"
+  | "ButtonGroup"
+  // Data
+  | "Table"
+  | "Carousel"
+  | "Badge"
+  | "Avatar"
+  | "Image"
+  // Feedback
+  | "Alert"
+  | "Progress"
+  | "Rating"
+  | "Skeleton"
+  | "Spinner"
+  // Navigation
+  | "Button"
+  | "Link"
+  | "DropdownMenu"
+  | "Tabs"
+  | "Pagination"
+  // Metric
+  | "Metric"
+  // Visualization
+  | "BarGraph"
+  | "LineGraph"
+  // Interaction
+  | "Tooltip"
+  | "Popover"
+  | "Collapsible"
+  | "Accordion"
+  | "Dialog"
+  | "Drawer";
+
+// ── Element definition ──────────────────────────────────────────────
+
+export interface UiElement {
+  type: UiComponentType;
+  props: Record<string, unknown>;
+  children: string[];
+  on?: UiEventBindings;
+  repeat?: RepeatConfig;
+  visible?: VisibilityCondition;
+  validation?: ValidationConfig;
+}
+
+// ── Full spec ───────────────────────────────────────────────────────
+
+export interface UiSpec {
+  root: string;
+  elements: Record<string, UiElement>;
+  state: Record<string, unknown>;
+}
+
+// ── Auth state (for visibility evaluation) ──────────────────────────
+
+export interface AuthState {
+  isSignedIn: boolean;
+  roles?: string[];
+}
+
+// ── Renderer context (passed through tree) ──────────────────────────
+
+export interface UiRenderContext {
+  spec: UiSpec;
+  state: Record<string, unknown>;
+  setState: (path: string, value: unknown) => void;
+  onAction?: (action: string, params?: Record<string, unknown>) => void;
+  /** Current repeat item data (set when inside a repeat block). */
+  repeatItem?: Record<string, unknown>;
+  /** Auth state for visibility evaluation. */
+  auth?: AuthState;
+  /** Whether the renderer is in a loading/streaming state. */
+  loading?: boolean;
+  /** Custom validator functions. */
+  validators?: Record<
+    string,
+    (
+      value: unknown,
+      args?: Record<string, unknown>,
+    ) => boolean | Promise<boolean>
+  >;
+  /** Field validation errors keyed by statePath. */
+  fieldErrors?: Record<string, string[]>;
+  /** Trigger validation for a field. */
+  validateField?: (statePath: string) => void;
+}
+
+// ── Streaming types ─────────────────────────────────────────────────
+
+/** RFC 6902 JSON Patch operation. */
+export type PatchOp =
+  | { op: "add"; path: string; value: unknown }
+  | { op: "remove"; path: string }
+  | { op: "replace"; path: string; value: unknown }
+  | { op: "move"; from: string; path: string }
+  | { op: "copy"; from: string; path: string }
+  | { op: "test"; path: string; value: unknown };
+
+/** Stream configuration for useUIStream. */
+export interface UIStreamConfig {
+  api: string;
+  onComplete?: (spec: UiSpec) => void;
+  onError?: (error: Error) => void;
+}

package/src/events/index.ts

@@ -0,0 +1,89 @@
+/**
+ * Typed constants for milady:* custom events dispatched across the app.
+ *
+ * Using these constants instead of raw strings prevents typo-driven drift
+ * between producers (main.tsx, bridge, components) and consumers (AppContext,
+ * EmotePicker, ChatView, etc.).
+ */
+
+// ── App lifecycle ────────────────────────────────────────────────────────
+export const COMMAND_PALETTE_EVENT = "milady:command-palette" as const;
+export const EMOTE_PICKER_EVENT = "milady:emote-picker" as const;
+export const STOP_EMOTE_EVENT = "milady:stop-emote" as const;
+
+// ── Agent / bridge ───────────────────────────────────────────────────────
+export const AGENT_READY_EVENT = "milady:agent-ready" as const;
+export const BRIDGE_READY_EVENT = "milady:bridge-ready" as const;
+export const SHARE_TARGET_EVENT = "milady:share-target" as const;
+export const TRAY_ACTION_EVENT = "milady:tray-action" as const;
+
+// ── App state ────────────────────────────────────────────────────────────
+export const APP_RESUME_EVENT = "milady:app-resume" as const;
+export const APP_PAUSE_EVENT = "milady:app-pause" as const;
+export const CONNECT_EVENT = "milady:connect" as const;
+
+// ── Voice / config ───────────────────────────────────────────────────────
+export const VOICE_CONFIG_UPDATED_EVENT =
+  "milady:voice-config-updated" as const;
+export const CHAT_AVATAR_VOICE_EVENT = "milady:chat-avatar-voice" as const;
+export const APP_EMOTE_EVENT = "milady:app-emote" as const;
+
+// ── Sidebar sync ─────────────────────────────────────────────────────────
+export const SELF_STATUS_SYNC_EVENT = "milady:self-status-refresh" as const;
+
+export interface AppEmoteEventDetail {
+  emoteId: string;
+  path: string;
+  duration: number;
+  loop: boolean;
+  showOverlay?: boolean;
+}
+
+export interface ChatAvatarVoiceEventDetail {
+  mouthOpen: number;
+  isSpeaking: boolean;
+}
+
+export type MiladyDocumentEventName =
+  | typeof COMMAND_PALETTE_EVENT
+  | typeof EMOTE_PICKER_EVENT
+  | typeof STOP_EMOTE_EVENT
+  | typeof AGENT_READY_EVENT
+  | typeof BRIDGE_READY_EVENT
+  | typeof SHARE_TARGET_EVENT
+  | typeof TRAY_ACTION_EVENT
+  | typeof APP_RESUME_EVENT
+  | typeof APP_PAUSE_EVENT
+  | typeof CONNECT_EVENT;
+
+export type MiladyWindowEventName =
+  | typeof VOICE_CONFIG_UPDATED_EVENT
+  | typeof CHAT_AVATAR_VOICE_EVENT
+  | typeof APP_EMOTE_EVENT
+  | typeof SELF_STATUS_SYNC_EVENT;
+
+export type MiladyEventName = MiladyDocumentEventName | MiladyWindowEventName;
+
+// ── Helpers ──────────────────────────────────────────────────────────────
+
+/** Dispatch a typed custom event on `document`. */
+export function dispatchMiladyEvent(
+  name: MiladyDocumentEventName,
+  detail?: unknown,
+): void {
+  document.dispatchEvent(new CustomEvent(name, { detail }));
+}
+
+/** Dispatch a typed custom event on `window`. */
+export function dispatchWindowEvent(
+  name: MiladyWindowEventName,
+  detail?: unknown,
+): void {
+  if (typeof window === "undefined") return;
+  window.dispatchEvent(new CustomEvent(name, { detail }));
+}
+
+/** Dispatch a normalized app-wide emote event on `window`. */
+export function dispatchAppEmoteEvent(detail: AppEmoteEventDetail): void {
+  dispatchWindowEvent(APP_EMOTE_EVENT, detail);
+}

package/src/hooks/index.ts

@@ -0,0 +1,13 @@
+export * from "./useBugReport";
+export * from "./useCanvasWindow";
+export * from "./useChatAvatarVoice";
+export * from "./useContextMenu";
+export * from "./useKeyboardShortcuts";
+export * from "./useLifoSync";
+export * from "./useMemoryMonitor";
+export * from "./useRenderGuard";
+export * from "./useRetakeCapture";
+export * from "./useStreamPopoutNavigation";
+export * from "./useTimeout";
+export * from "./useVoiceChat";
+export * from "./useWhatsAppPairing";

package/src/hooks/useBugReport.tsx

@@ -0,0 +1,43 @@
+import {
+  createContext,
+  type ReactNode,
+  useCallback,
+  useContext,
+  useState,
+} from "react";
+
+interface BugReportContextValue {
+  isOpen: boolean;
+  open: () => void;
+  close: () => void;
+}
+
+const BugReportContext = createContext<BugReportContextValue | null>(null);
+
+export function useBugReport(): BugReportContextValue {
+  const ctx = useContext(BugReportContext);
+  if (!ctx)
+    throw new Error("useBugReport must be used within BugReportProvider");
+  return ctx;
+}
+
+export function useBugReportState(): BugReportContextValue {
+  const [isOpen, setIsOpen] = useState(false);
+  const open = useCallback(() => setIsOpen(true), []);
+  const close = useCallback(() => setIsOpen(false), []);
+  return { isOpen, open, close };
+}
+
+export function BugReportProvider({
+  children,
+  value,
+}: {
+  children: ReactNode;
+  value: BugReportContextValue;
+}) {
+  return (
+    <BugReportContext.Provider value={value}>
+      {children}
+    </BugReportContext.Provider>
+  );
+}