Skip to content

The Open Standard for Generative UI

5.0 KB
Raw Blame
import type { EvaluationContext, Store } from "@openuidev/lang-core";
import type { InjectionKey, Ref } from "vue";
import { inject, provide, watchEffect } from "vue";
import type { Library, RenderNodeResult } from "./library.js";

// ─── Action config ───

export interface ActionConfig {
  type?: string;
  params?: Record<string, any>;
}

// ─── OpenUI context ───

/**
 * Shared context provided by <Renderer /> to all rendered components.
 *
 * Vue passes `renderNode` via context, idiomatic for Vue's provide/inject model.
 */
export interface OpenUIContextValue {
  /** The active component library (schema + renderers). */
  library: Library;

  /** Render a parsed value into VNodes. */
  renderNode: (value: unknown) => RenderNodeResult;

  /**
   * Trigger an action. Components call this to fire structured ActionEvents.
   *
   * @param userMessage  Human-readable label ("Submit Application")
   * @param formName  Optional form name — if provided, form state for this form is included
   * @param action  Optional custom action config { type, params }
   */
  triggerAction: (userMessage: string, formName?: string, action?: ActionConfig) => void;

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

  /** Whether any Query is currently fetching data. */
  isQueryLoading: Ref<boolean>;

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

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

  /** Get a form field value. Returns undefined if not set. */
  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", "RadioGroup")
   * @param name  The field's name prop
   * @param value  The new value
   * @param shouldTriggerSaveCallback  When true, persists the updated state via updateMessage.
   *   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: any,
    shouldTriggerSaveCallback?: boolean,
  ) => void;
}

const OPENUI_CONTEXT_KEY: InjectionKey<OpenUIContextValue> = Symbol("openui-context");
const FORM_NAME_CONTEXT_KEY: InjectionKey<Ref<string | undefined>> = Symbol("openui-form-name");

// ─── Context providers ───

export function provideOpenUIContext(value: OpenUIContextValue): void {
  provide(OPENUI_CONTEXT_KEY, value);
}

export function provideFormName(formName: Ref<string | undefined>): void {
  provide(FORM_NAME_CONTEXT_KEY, formName);
}

// ─── Context consumers (composables) ───

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

/**
 * Get the renderNode function for rendering child values into VNodes.
 */
export function useRenderNode() {
  return useOpenUI().renderNode;
}

/**
 * Get the triggerAction function for firing structured action events.
 */
export function useTriggerAction() {
  return useOpenUI().triggerAction;
}

/**
 * Returns the reactive isStreaming ref.
 * Use as: `const isStreaming = useIsStreaming(); ... :disabled="isStreaming"`
 */
export function useIsStreaming(): Ref<boolean> {
  return useOpenUI().isStreaming;
}

/**
 * Whether any Query is currently fetching data.
 */
export function useIsQueryLoading(): Ref<boolean> {
  return useOpenUI().isQueryLoading;
}

/**
 * Get a form field value from the form state context.
 */
export function useGetFieldValue() {
  return useOpenUI().getFieldValue;
}

/**
 * Get the setFieldValue function for updating form field values.
 */
export function useSetFieldValue() {
  return useOpenUI().setFieldValue;
}

/**
 * Get the current form name (set by the nearest parent Form component).
 * Returns a ref that may be undefined if not inside a Form.
 */
export function useFormName(): Ref<string | undefined> | undefined {
  return inject(FORM_NAME_CONTEXT_KEY);
}

// ─── 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.
 */
export function useSetDefaultValue({
  formName,
  componentType,
  name,
  defaultValue,
  shouldTriggerSaveCallback = false,
}: {
  formName?: string;
  componentType: string;
  name: string;
  defaultValue: any;
  shouldTriggerSaveCallback?: boolean;
}): void {
  const ctx = useOpenUI();

  watchEffect(() => {
    const existing = ctx.getFieldValue(formName, name);
    if (!ctx.isStreaming.value && existing === undefined && defaultValue !== undefined) {
      ctx.setFieldValue(formName, componentType, name, defaultValue, shouldTriggerSaveCallback);
    }
  });
}