@heylock-dev/ui/dist/types.d.ts

Heylock UI React component library

import * as React from 'react';
import type Heylock from 'heylock';
import { AgentOptions } from 'heylock';

/** Theme options supported across UI components */
export type HeylockTheme = 'light' | 'dark' | 'auto';

/** Props for the provider that instantiates and exposes a Heylock agent via context */
export interface HeylockProviderProps {
  /** Children that can access the agent through useAgent */
  children?: React.ReactNode;
  /** API agent key (required). Provider will throw early if missing. */
  agentKey: string;
  /** Optional agent options to pass during initialization */
  options?: AgentOptions;
}

/**
 * HeylockProvider
 *
 * Wrap your app with this provider to initialize the Heylock agent and expose
 * it via context to child components (use `useAgent` to access it).
 *
 * Behaviour notes:
 * - The provider will synchronously validate `agentKey` and throw if missing.
 * - It performs lightweight setup only; long-running network calls are handled
 *   by the underlying agent instance.
 *
 * @props
 * - `agentKey`: string — API agent key (required). Provider will throw early if missing.
 * - `options`?: AgentOptions — Optional agent options to pass during initialization.
 * - `children`?: React.ReactNode — Children that can access the agent through `useAgent`.
 *
 * @returns React.FC — a provider component that supplies the Heylock agent via context.
 *
 * @throws {Error} If `agentKey` is not a valid string.
 */
export declare const HeylockProvider: React.FC<HeylockProviderProps>;

/**
 * useAgent
 *
 * Returns the Heylock agent instance created by the closest `HeylockProvider`.
 *
 * Usage:
 * - Call from any child of `HeylockProvider`.
 * - The returned object is the same agent instance for the provider's lifetime.
 *
 * @returns Heylock — the Heylock agent instance from context.
 *
 * @throws {Error} If called outside a `HeylockProvider`.
 */
export declare function useAgent(): Heylock;

/** Props for the expanding chat wrapper component */
export interface HeylockExpandingChatProps extends React.HTMLAttributes<HTMLDivElement> {
  /** Outer container className (positioning, sizing). */
  className?: string;
  /** Class applied to the animated message container panel. */
  messageContainerClassName?: string;
  /** Class applied to the header bar inside the panel. */
  headerClassName?: string;
  /** Class applied to the close (X) button. */
  closeButtonClassName?: string;
  /** Whether input (and open interaction) is disabled. Defaults to false. */
  disabled?: boolean;
  /** Visual theme; 'auto' applies dark based on prefers-color-scheme. */
  theme?: HeylockTheme;
  /** Header text shown in the panel. */
  header?: string;
}

/**
 * HeylockExpandingChat
 *
 * A small, animated chat widget that expands into a conversation panel when
 * opened.
 *
 * @props
 * - `className`?: string — Outer container className (positioning, sizing).
 * - `messageContainerClassName`?: string — Class applied to the animated message container panel.
 * - `headerClassName`?: string — Class applied to the header bar inside the panel.
 * - `closeButtonClassName`?: string — Class applied to the close (X) button.
 * - `disabled`?: boolean — Whether input (and open interaction) is disabled. Defaults to false.
 * - `theme`?: HeylockTheme — Visual theme; 'auto' applies dark based on prefers-color-scheme.
 * - `header`?: string — Header text shown in the panel.
 * - (extends) `React.HTMLAttributes<HTMLDivElement>` — Standard div props like id, style, onClick etc.
 */
export declare const HeylockExpandingChat: React.FC<HeylockExpandingChatProps>;

/** Props for the chat input form */
export interface HeylockInputProps extends Omit<React.FormHTMLAttributes<HTMLFormElement>, 'onSubmit' | 'onChange' | 'onFocus'> {
  /** Disable the input externally (usage limits may also disable internally). */
  disabled?: boolean;
  /** Text shown when disabled due to limits or explicit disable. */
  disabledText?: string;
  /** Placeholder text shown while streaming a response. */
  respondingText?: string;
  /** Theme variant for styling. */
  theme?: HeylockTheme;
  /** Rotating placeholder strings (cycles over time). */
  placeholders?: string[];
  /** Interval (ms) for rotating placeholders. */
  placeholderInterval?: number;
  /** Root form className. */
  className?: string;
  /** Input element className. */
  inputClassName?: string;
  /** Placeholder element className. */
  placeholderClassName?: string;
  /** Submit button className. */
  buttonClassName?: string;
  /** Arrow SVG className. */
  arrowClassName?: string;
  /** Input change handler (fires only when not animating / not disabled). */
  onChange?: React.ChangeEventHandler<HTMLInputElement>;
  /** Form submit handler (called prior to internal streaming). */
  onSubmit?: React.FormEventHandler<HTMLFormElement>;
  /** Focus handler for the form. */
  onFocus?: React.FocusEventHandler<HTMLFormElement>;
}

/**
 * HeylockInput
 *
 * Input form used to send prompts to the Heylock agent. The
 * component manages the streaming response lifecycle by default (it will call
 * the agent, stream partial content to the UI, and finish when the agent
 * completes). Consumers can intercept `onSubmit` to run custom logic before
 * the default send behavior, or return `false`/preventDefault to stop internal
 * submission.
 *
 * @props
 * - `disabled`?: boolean — Disable the input externally (usage limits may also disable internally).
 * - `disabledText`?: string — Text shown when disabled due to limits or explicit disable.
 * - `respondingText`?: string — Placeholder text shown while streaming a response.
 * - `theme`?: HeylockTheme — Theme variant for styling.
 * - `placeholders`?: string[] — Rotating placeholder strings (cycles over time).
 * - `placeholderInterval`?: number — Interval (ms) for rotating placeholders.
 * - `className`?: string — Root form className.
 * - `inputClassName`?: string — Input element className.
 * - `placeholderClassName`?: string — Placeholder element className.
 * - `buttonClassName`?: string — Submit button className.
 * - `arrowClassName`?: string — Arrow SVG className.
 * - `onChange`?: React.ChangeEventHandler<HTMLInputElement> — Input change handler (fires only when not animating / not disabled).
 * - `onSubmit`?: React.FormEventHandler<HTMLFormElement> — Form submit handler (called prior to internal streaming).
 * - `onFocus`?: React.FocusEventHandler<HTMLFormElement> — Focus handler for the form.
 * - (extends) `Omit<React.FormHTMLAttributes<HTMLFormElement>, 'onSubmit' | 'onChange' | 'onFocus'>` — Other standard form props.
 */
export declare const HeylockInput: React.FC<HeylockInputProps>;

/** Props for the messages list component */
export interface HeylockMessagesProps extends React.HTMLAttributes<HTMLDivElement> {
  /** Root container className (scroll area). */
  className?: string;
  /** ClassName applied to user messages. */
  userMessageClassName?: string;
  /** ClassName applied to assistant messages. */
  assistantMessageClassName?: string;
}

/**
 * HeylockMessages
 *
 * Renders a chronological list of chat messages. It expects the surrounding
 * provider or parent to populate messages via the Heylock agent.
 *
 * @props
 * - `className`?: string — Root container className (scroll area).
 * - `userMessageClassName`?: string — ClassName applied to user messages.
 * - `assistantMessageClassName`?: string — ClassName applied to assistant messages.
 * - (extends) `React.HTMLAttributes<HTMLDivElement>` — Standard div props like id, style, etc.
 */
export declare const HeylockMessages: React.FC<HeylockMessagesProps>;

/** Re-export core Heylock types for convenience */
export type { Message, UsageRemaining, AgentOptions } from 'heylock/dist/types';