Skip to content

The Open Standard for Generative UI

5.5 KB
Raw Blame
import type { ActionPlan, EvaluationContext, OpenUIError, Store } from "@openuidev/lang-core";
import type { ReactNode } from "react";
import { createContext, useContext, useEffect } from "react";
import type { Library } from "./library";

export interface OpenUIContextValue {
  /** The active component library (schema + renderers). */
  library: Library;

  /**
   * Render any value (element, array, primitive) into React nodes.
   */
  renderNode: (value: unknown) => ReactNode;

  /**
   * Trigger an action. Accepts either:
   * - ActionPlan (v0.5): runs steps sequentially (Run, Set, ToAssistant, OpenUrl)
   * - Legacy action config (v0.1): { type?: string, params?: Record<string, any> }
   * - Nothing: fires ContinueConversation with the label
   */
  triggerAction: (
    userMessage: string,
    formName?: string,
    action?: ActionPlan | { type?: string; params?: Record<string, any> },
  ) => void | Promise<void>;

  /** Whether the LLM is currently streaming content. */
  isStreaming: boolean;

  /** Whether any Query is currently fetching data (e.g., MCP tool calls in-flight). */
  isQueryLoading: boolean;

  /** Get a field value. Top-level for $bindings, nested under formName for form fields. */
  getFieldValue: (formName: string | undefined, name: string) => any;

  /**
   * Set a form field value.
   *
   * @param formName  The form's name prop
   * @param componentType  The component type (e.g. "Input", "Select") — optional
   * @param name  The field's name prop
   * @param value  The new value
   * @param shouldTriggerSaveCallback  When true, persists state via onStateUpdate.
   *   Text inputs should pass `false` on change and `true` on blur.
   *   Discrete inputs (Select, RadioGroup, etc.) should always pass `true`.
   */
  setFieldValue: (
    formName: string | undefined,
    componentType: string | undefined,
    name: string,
    value: unknown,
    shouldTriggerSaveCallback?: boolean,
  ) => void;

  /** Reactive binding store for $variables and form data. */
  store: Store;

  /** AST evaluation context used by runtime expression evaluation. */
  evaluationContext: EvaluationContext;

  /** Report a structured error (used internally by error boundary). */
  reportError?: (error: OpenUIError) => void;
}

export const OpenUIContext = createContext<OpenUIContextValue | null>(null);

/**
 * Access the full OpenUI context. Throws if used outside a <Renderer />.
 */
export function useOpenUI(): OpenUIContextValue {
  const ctx = useContext(OpenUIContext);
  if (!ctx) {
    throw new Error("useOpenUI must be used within a <Renderer /> component.");
  }
  return ctx;
}

/**
 * Get the renderNode function for rendering nested component values.
 */
export function useRenderNode() {
  return useOpenUI().renderNode;
}

/**
 * Get the triggerAction function for firing structured action events.
 *
 * @example
 * ```tsx
 * const triggerAction = useTriggerAction();
 * <button onClick={() => triggerAction("Submit", "myForm")}>
 * ```
 */
export function useTriggerAction() {
  return useOpenUI().triggerAction;
}

/**
 * Whether the LLM is currently streaming content.
 */
export function useIsStreaming() {
  return useOpenUI().isStreaming;
}

/**
 * Whether any Query is currently fetching data.
 * Useful for showing skeleton/loading states in data-driven components.
 */
export function useIsQueryLoading() {
  return useOpenUI().isQueryLoading;
}

/**
 * Get a form field value from the form state context.
 *
 * @example
 * ```tsx
 * const getFieldValue = useGetFieldValue();
 * const name = getFieldValue("contactForm", "name");
 * ```
 */
export function useGetFieldValue() {
  return useOpenUI().getFieldValue;
}

/**
 * Get the setFieldValue function for updating form field values.
 *
 * @example
 * ```tsx
 * const setFieldValue = useSetFieldValue();
 * <input onChange={(e) => setFieldValue("contactForm", "Input", "name", e.target.value, false)} />
 * ```
 */
export function useSetFieldValue() {
  return useOpenUI().setFieldValue;
}

// ─── FormName context ───

export const FormNameContext = createContext<string | undefined>(undefined);

/**
 * Get the current form name (set by the nearest parent Form component).
 * Returns undefined if not inside a Form.
 */
export function useFormName(): string | undefined {
  return useContext(FormNameContext);
}

// ─── Default value helper ───

/**
 * Persists a component's default/initial value into form state once streaming
 * finishes — but only if the user hasn't already set a value.
 *
 * Call this inside any form component that has a `defaultValue` or
 * `defaultChecked` prop. It is a no-op during streaming so that LLM
 * prop changes don't fight with partial state.
 *
 * @param shouldTriggerSaveCallback — defaults to `false` (only local state, no message persistence)
 */
export function useSetDefaultValue({
  formName,
  componentType,
  name,
  existingValue,
  defaultValue,
  shouldTriggerSaveCallback = false,
}: {
  formName?: string;
  componentType?: string;
  name: string;
  existingValue: unknown;
  defaultValue: unknown;
  shouldTriggerSaveCallback?: boolean;
}) {
  const setFieldValue = useSetFieldValue();
  const isStreaming = useIsStreaming();

  useEffect(() => {
    if (!isStreaming && existingValue === undefined && defaultValue !== undefined) {
      setFieldValue(formName, componentType, name, defaultValue, shouldTriggerSaveCallback);
    }
  }, [
    defaultValue,
    existingValue,
    formName,
    componentType,
    name,
    isStreaming,
    setFieldValue,
    shouldTriggerSaveCallback,
  ]);
}