@hyperflow/chakra-ui

export interface HyperflowAppProps
  extends Omit<
    AppCoreProps,
    "layoutComponent" | "loginComponent" | "runtimeReloadComponent"
  > {
  layoutComponent?: React.ComponentType<{ children: React.ReactNode }>;
  loginComponent?: React.ComponentType;
  runtimeReloadComponent?: React.ComponentType;
  chakraProvider?: React.ComponentType<{ children: React.ReactNode }>;
}

/**
 * Default Chakra UI layout shell for Hyperflow applications.
 *
 * Renders the active sidebar component on the left, the top bar and routed
 * page content in the main area on the right.
 *
 * Pass this as the `layoutComponent` to `HyperflowApp` from `@hyperflow/chakra-ui`.
 * The router will inject the active route as `children` automatically.
 */
export interface LayoutProps {
    /** Main routed content rendered inside the layout. */
    children: React.ReactNode;
    /**
     * Optional sidebar component used to replace the default `SessionSidebar`
     * implementation.
     */
    sidebarComponent?: React.ComponentType<SidebarComponentProps>;
    /**
     * Optional top bar component used to replace the default `SessionTopBar`
     * implementation.
     */
    topbarComponent?: React.ComponentType;
    /**
     * Optional drawer component used to replace the default background-task
     * drawer.
     */
    drawerComponent?: React.ComponentType;
}

/**
 * Props accepted by sidebar components used in {@link Layout}.
 */
export type SidebarComponentProps = BaseSidebarProps | SessionSidebarProps;

interface BaseSidebarProps {
    /**
     * Optional custom content rendered between the navigation section and the footer.
     */
    children?: React.ReactNode;
    /**
     * Custom header component used to render the top section of the sidebar.
     */
    headerComponent?: React.ComponentType<SidebarHeaderProps>;
    /**
     * Custom footer component used to render the bottom section of the sidebar.
     */
    footerComponent?: React.ComponentType<SidebarFooterProps>;
}

type LoginProps = {
    /** Optional logo URL shown above the form. */
    logo?: string;
    /** Screen title displayed above the form. */
    title?: string;
    /** Route navigated to after successful login. */
    redirectTo?: string;
};

interface ColorModeProviderProps extends ThemeProviderProps {}

interface ColorModeButtonProps extends Omit<IconButtonProps, "aria-label"> {
}

/**
 * Props for the session-oriented sidebar preset.
 */
export interface SessionSidebarProps {
    /** Custom header component used to render the top section of the sidebar. */
    headerComponent?: React.ComponentType<SidebarHeaderProps>;
    /** Custom footer component used to render the bottom section of the sidebar. */
    footerComponent?: React.ComponentType<SidebarFooterProps>;
    /** Display label for sessions not assigned to a custom group. */
    customUngroupedDisplayName?: string;
    /** Display labels for status-group headers, keyed by normalized status. */
    statusGroupLabels?: Record<string, string>;
}

interface SidebarHeaderProps {
    /**
     * Custom title component used to render the sidebar title.
     */
    titleComponent?: React.ComponentType;
}

type SidebarFooterProps = {
    /** Custom account menu rendered at the bottom of the sidebar. */
    accountMenuComponent?: ComponentType<SidebarAccountMenuProps>;
};

type SidebarAccountMenuProps = {
    items?: SidebarAccountMenuItemConfig[];
    showDisplayName?: boolean;
    collapseLabel?: boolean;
    positioning?: ComponentProps<typeof Menu.Root>["positioning"];
};

type SessionTopBarProps = {
    /** Session action menu. Defaults to {@link SessionMoreMenu}. */
    moreMenuComponent?: ComponentType<SessionMoreMenuProps> | undefined;
    /** Overrides visible copy in the default session action menu. */
    moreMenuLabels?: SessionMoreMenuLabels | undefined;
};

type SessionMoreMenuProps = {
    session: Session;
    customGroups?: SessionCustomGroup[] | undefined;
    onRename: (title: string) => Promise<void>;
    onMoveToGroup?: ((customGroupId: string | null) => void | Promise<void>) | undefined;
    onDelete: () => Promise<void>;
    /** Overrides visible copy in the session action menu and dialogs. */
    labels?: SessionMoreMenuLabels | undefined;
};

type SessionMoreMenuLabels = {
    backgroundTasks?: string;
    moveToGroup?: string;
    removeFromGroup?: string;
    rename?: string;
    delete?: string;
    options?: string;
    renameDialogTitle?: string;
    deleteDialogTitle?: string;
    titleLabel?: string;
    deleteConfirmation?: string;
};

type SessionBackgroundTasksDrawerProps = {
    /** Overrides visible copy in the default task panel. */
    labels?: BackgroundTasksPanelLabels | undefined;
    /** Overrides visible copy in conversation transcripts. */
    conversationLabels?: BackgroundTaskConversationLabels | undefined;
    /** Overrides visible copy in terminal transcripts. */
    terminalLabels?: BackgroundTaskTerminalLabels | undefined;
};

type BackgroundTasksPanelLabels = {
    title?: string;
    close?: string;
    running?: string;
    finishedOne?: string;
    finishedMany?: string;
    clearFinished?: string;
    empty?: string;
    defaultLabel?: string;
    cancelTask?: string;
    removeTask?: string;
    cancel?: string;
    remove?: string;
    back?: string;
    tool?: string;
    pending?: string;
    inputTokens?: string;
    outputTokens?: string;
};

type BackgroundTaskConversationLabels = {
    tool?: string;
    pending?: string;
};

type BackgroundTaskTerminalLabels = {
    title?: string;
    waiting?: string;
};

type SidebarAccountMenuItemConfig = {
    key: string;
    component: ComponentType<SidebarAccountMenuItemProps>;
    separatorBefore?: boolean;
};

type TriggerButtonLayout = "compact" | "panel";

type SelectionMenuPlacement = "top-start" | "top-end" | "left-start";

type SidebarAccountMenuItemProps = {
    onCloseMenu?: () => void;
};

interface ComposerProps {
    inputComponent?: ComponentType<ComposerTextInputProps> | undefined;
    sendButtonComponent?: ComponentType<ComposerSendButtonProps> | undefined;
    attachmentMenuComponent?: ComponentType<ComposerAttachmentMenuProps> | undefined;
    attachmentPreviewComponent?: ComponentType<ComposerAttachmentPreviewProps> | undefined;
    slotRenderers?: ComposerSlotRenderers | undefined;
    onSubmitOverride?: ((composer: UseComposer) => Promise<ComposerSubmitResult | void> | ComposerSubmitResult | void) | undefined;
    submitting?: boolean | undefined;
    /** Visual treatment for top and bottom slot regions. Defaults to the neutral rows. */
    slotSurfaceVariant?: ComposerSlotSurfaceVariant | undefined;
    /** Visual context for the composer. Defaults to the standalone new-session placement. */
    placement?: ComposerPlacement | undefined;
    /** Positioned element that accepts dropped files. Defaults to the composer itself. */
    dropTarget?: HTMLElement | null | undefined;
}

interface ComposerTextInputProps {
    value: string;
    disabled: boolean;
    onChange: ChangeEventHandler<HTMLTextAreaElement>;
    onKeyDown: KeyboardEventHandler<HTMLTextAreaElement>;
    onDragOver?: DragEventHandler<HTMLElement> | undefined;
    onDrop?: DragEventHandler<HTMLElement> | undefined;
    onPaste?: ClipboardEventHandler<HTMLTextAreaElement> | undefined;
    /** Placeholder shown while the draft is empty. */
    placeholder?: string | undefined;
}

interface ComposerSendButtonProps {
    submitLabel?: string | undefined;
    canSubmit: boolean;
    isBusy: boolean;
    isGenerating?: boolean;
    isStopping?: boolean | undefined;
    onStop?: MouseEventHandler<HTMLButtonElement>;
}

type ComposerAttachmentMenuProps = {
    /** Native file input props supplied by `useComposer().draft`. */
    inputProps: Pick<InputHTMLAttributes<HTMLInputElement>, "disabled" | "onChange" | "accept">;
};

type ComposerAttachmentPreviewProps = {
    attachments: readonly ComposerAttachmentItem[];
};

type AgentSelectorProps = ComponentProps<SlotRenderer<ComposerSlotControls["agent"]>> & {
    /** Optional labels for the trigger, menu title, and empty state. */
    labels?: AgentSelectorLabels | undefined;
    triggerProps?: SelectionMenuProps["triggerProps"];
    /** Visual layout used by the trigger and menu. */
    layout?: SelectionMenuProps["layout"] | undefined;
};

type ModelReasoningSelectorProps = ComponentProps<SlotRenderer<ComposerSlotControls["model"]>> & {
    /** Optional labels for the trigger and provider/model/reasoning sections. */
    labels?: ModelReasoningSelectorLabels | undefined;
    triggerProps?: Partial<Pick<TriggerButtonProps, "bg" | "_hover" | "labelProps">> | undefined;
    /** Visual layout used by the trigger and menu. */
    layout?: TriggerButtonProps["layout"] | undefined;
};

type ToolhostSelectorProps = ComponentProps<SlotRenderer<ComposerSlotControls["toolhost"]>> & {
    /** Optional labels for the trigger, title, and empty state. */
    labels?: ToolhostSelectorLabels | undefined;
    triggerProps?: Partial<Pick<TriggerButtonProps, "bg" | "_hover" | "labelProps">> | undefined;
    /** Runtime id of the current desktop toolhost, used to label it as the local computer. */
    currentToolhostId?: string | undefined;
    /** Preferred display order for the built-in toolhost categories. */
    categoryOrder?: readonly ToolhostCategory[] | undefined;
    /** Visual layout used by the trigger and menu. */
    layout?: TriggerButtonProps["layout"] | undefined;
};

type ContextWindowMeterProps = ComponentProps<SlotRenderer<ComposerSlotControls["contextWindow"]>> & {
    /** Settings route opened from the plan-usage header. Pass `null` to hide the action. */
    usageSettingsPath?: string | null | undefined;
    /** Custom action opened from the plan-usage header. Overrides `usageSettingsPath`. */
    onOpenUsage?: (() => void) | undefined;
};

type SessionOptionsPanelProps = {
    composer: UseComposer;
};

type ComposerSlotRenderers = Partial<ComposerSlotRendererMap>;

type ComposerSlotSurfaceVariant = "plain" | "appendix";

type ComposerPlacement = "standalone" | "floating";

type ComposerSlotRendererMap = {
    [K in ComposerPositionableSlotKey]: SlotRenderer<ComposerSlotControls[K]>;
};

type ComposerAttachmentItem = {
    id: string;
    file: File;
    name: string;
    remove: () => void;
    preparation?: DocumentAttachmentState | undefined;
    retry?: (() => void) | undefined;
};

type AgentSelectorLabels = {
    trigger?: string;
    title?: string;
    empty?: string;
};

type ModelReasoningSelectorLabels = {
    trigger?: string;
    reasoning?: string;
    effort?: string;
    provider?: string;
    models?: string;
};

type ToolhostSelectorLabels = {
    trigger?: string;
    title?: string;
    empty?: string;
};

type ToolhostCategory = ComposerToolhostCategory;

type ComposerPositionableSlotKey = Exclude<keyof ComposerSlotControls, "status">;

type ActTimelineProps<EntryProps extends object = Record<never, never>> = {
    /** Scroll and history container. Defaults to {@link TimelineViewport}. */
    viewportComponent?: ComponentType<TimelineViewportProps> | undefined;
    /** Initial history loading feedback. */
    loadingComponent?: ComponentType | undefined;
    /** Blocking initial history error feedback. */
    errorComponent?: ComponentType<TimelineErrorProps> | undefined;
    /** Feedback shown when no semantic entries are available. */
    emptyStateComponent?: ComponentType<TimelineEmptyStateProps> | undefined;
} & TimelineEntryRendererProps<EntryProps>;

type TimelineViewportProps<EntryProps extends object = Record<never, never>> = {
    /** Entries used as the scroll anchoring signal. */
    entries: readonly TimelineEntry[];
    /** Older-history state and pagination action. */
    history: TimelineHistory;
    /** Custom content, or feedback displayed after entries when entryComponent is provided. */
    children?: ReactNode;
    /** Loading feedback shown while older history is loading. */
    historyLoadingComponent?: ComponentType | undefined;
} & TimelineEntryRendererProps<EntryProps>;

type TimelineEntryViewProps = {
    /** Semantic entry to render. */
    entry: TimelineEntry;
    /** Renderer for `user_message` entries. */
    userMessageComponent?: ComponentType<UserMessageProps> | undefined;
    /** Renderer for `assistant_message` entries. */
    assistantMessageComponent?: ComponentType<AssistantMessageProps> | undefined;
    /** Renderer for `compaction` entries. */
    compactionComponent?: ComponentType<CompactionItemProps> | undefined;
    /** Renderer for `session_change` entries. */
    sessionChangeComponent?: ComponentType<SessionChangeItemProps> | undefined;
    /** Renderer for `tool_group` entries. */
    toolGroupComponent?: ComponentType<ToolGroupItemProps> | undefined;
    /** Renderer for `draft` entries. */
    /** Renderer for `thinking` entries. */
    thinkingComponent?: ComponentType<TimelineThinkingProps> | undefined;
    /** Renderer for `streaming_message` entries. */
    streamingMessageComponent?: ComponentType<TimelineStreamingMessageProps> | undefined;
    /** Renderer for `work_duration` entries. */
    workDurationComponent?: ComponentType<TimelineWorkDurationProps> | undefined;
    sessionErrorComponent?: ComponentType<TimelineSessionErrorProps> | undefined;
    /** Renderer for `act_error` entries. Pass `null` to hide them. */
    actErrorComponent?: ComponentType<TimelineActErrorProps> | null | undefined;
    /** Renderer for `act_note` entries. */
    actNoteComponent?: ComponentType<TimelineActNoteProps> | undefined;
    /** Renderer for `background_task_group` entries. */
    backgroundTaskComponent?: ComponentType<BackgroundTaskGroupProps> | undefined;
    /** Renderer for `background_task_completed` entries. */
    backgroundTaskCompletionComponent?: ComponentType<BackgroundTaskCompletionProps> | undefined;
};

type UserMessageProps<ActionsProps extends object = Record<never, never>> = {
    item: SessionItem;
    text?: string;
    /** Custom attachments below the message. Defaults to {@link MessageAttachments}. */
    attachmentsComponent?: ComponentType<MessageAttachmentsProps>;
    /** Extra props for the message bubble container. */
    bubbleProps?: BoxProps | undefined;
} & MessageActionsSlotProps<ActionsProps>;

type AssistantMessageProps<ActionsProps extends object = Record<never, never>> = {
    item: SessionItem;
    text: string;
    /** Retained semantic turn metadata; actions render for every message. */
    isLastInTurn?: boolean | undefined;
    /** Custom attachments below the message. Defaults to {@link MessageAttachments}. */
    attachmentsComponent?: ComponentType<MessageAttachmentsProps>;
} & MessageActionsSlotProps<ActionsProps>;

type MessageAttachmentsProps = {
    item: SessionItem;
};

type MessageActionsProps = {
    item: SessionItem;
    text?: string;
    /** Align timestamp/copy under the bubble. */
    align?: "start" | "end";
    /** Keeps actions visible outside hover, for composed active states. */
    forceVisible?: boolean | undefined;
    /** Extra controls rendered before copy/timestamp. */
    children?: ReactNode;
};

type TimelineThinkingProps = {
    text: string;
    streaming: boolean;
};

type TimelineStreamingMessageProps = {
    content: string;
};

type TimelineWorkDurationProps = {
    startedAt?: string | undefined;
    hidden?: boolean | undefined;
};

type TimelineEmptyStateProps = {
    /** Message shown when the timeline has no visible content. */
    message?: string;
};

type TimelineErrorProps = {
    error: Error;
    /** Message shown when the initial act history load fails. */
    message?: string;
};

type TimelineSessionErrorProps = {
    message: string;
};

type TimelineActErrorProps = {
    actId: string;
    message: string;
};

type TimelineActNoteProps = {
    actId: string;
    message: string;
};

type ToolGroupItemProps = {
    pairs: ToolCallPair[];
    toolResources: Record<string, ResourceLink>;
    locale?: string;
    /** Text shown when a tool requests input without question metadata. */
    inputRequiredMessage?: string;
    /** When true, animates the group or active tool label during streaming. */
    streaming?: boolean;
    labelContext?: ToolLabelContext;
};

type ReasoningItemProps = {
    item: SessionItem;
};

type ReasoningCollapsibleProps = {
    text: string;
    label?: string;
    /** Streaming mode adds the in-progress label and scrollable body. */
    streaming?: boolean;
};

type CompactionItemProps = {
    item: SessionItem;
    /** Overrides visible copy in the context-compaction marker. */
    labels?: CompactionItemLabels | undefined;
};

type SessionChangeItemProps = {
    item: SessionItem;
    /** Overrides visible copy in the session-change marker. */
    labels?: SessionChangeItemLabels | undefined;
};

type BackgroundTaskGroupProps = {
    tasks: Array<{
        item: SessionItem;
        taskId: string;
        task?: BackgroundTask | undefined;
    }>;
    /** Whether the task was received through a live update in this page lifetime. */
    live?: boolean | undefined;
    /** Overrides visible copy in the task-group trigger. */
    labels?: BackgroundTaskGroupLabels | undefined;
};

type BackgroundTaskCompletionProps = {
    item: SessionItem;
    task?: BackgroundTask | undefined;
    taskId?: string | undefined;
    /** Overrides visible copy in the completion marker. */
    labels?: BackgroundTaskCompletionLabels | undefined;
};

type TimelineEntryRendererProps<EntryProps extends object> = DefaultEntryProps | CustomEntryProps<EntryProps>;

type DefaultEntryProps = {
    /** Stable semantic entry renderer. */
    entryComponent?: ComponentType<TimelineEntryViewProps> | undefined;
    entryProps?: never;
};

type CustomEntryProps<EntryProps extends object> = {
    /** Stable entry renderer receiving caller-owned props. */
    entryComponent: ComponentType<TimelineEntryViewProps & EntryProps>;
    /** Additional typed props. The timeline supplies `entry`. */
    entryProps: EntryProps;
};

type DraftViewProps = {
    draft: StreamingDraft;
};

type MessageActionsSlotProps<ActionsProps extends object> = DefaultActionsSlotProps | CustomActionsSlotProps<ActionsProps>;

type DefaultActionsSlotProps = {
    /** Custom actions below the message. Defaults to {@link MessageActions}. */
    actionsComponent?: ComponentType<MessageActionsProps> | undefined;
    actionsProps?: never;
};

type CustomActionsSlotProps<ActionsProps extends object> = {
    /** Stable actions component receiving additional caller-owned props. */
    actionsComponent: ComponentType<MessageActionsProps & ActionsProps>;
    /** Additional typed props. The message supplies `item`, `text`, and `align`. */
    actionsProps: ActionsProps;
};

type CompactionItemLabels = {
    running?: ReactNode;
    completed?: (duration: string) => ReactNode;
    duration?: (seconds: number) => string;
};

type SessionChangeItemLabels = {
    defaultValue?: string;
    enabled?: string;
    disabled?: string;
    activeAgent?: (previous: string, current: string) => string;
    model?: (previous: string, current: string) => string;
};

type BackgroundTaskGroupLabels = {
    running?: (count: number) => string;
    total?: (count: number) => string;
    defaultTaskLabel?: string;
};

type BackgroundTaskCompletionLabels = {
    task?: string;
    failed?: string;
    cancelled?: string;
    timedOut?: string;
    finished?: string;
    durationPrefix?: string;
};

type HitlOverlayProps = {
    /**
     * Custom panel for tool input requests.
     * Defaults to {@link InputPanel}.
     */
    inputPanelComponent?: ComponentType;
    /**
     * Custom panel for tool approval requests.
     * Defaults to {@link ApprovalPanel}.
     */
    approvalPanelComponent?: ComponentType<ApprovalPanelProps>;
    /**
     * Custom panel for agent auth requests.
     * Defaults to {@link AgentAuthPanel}.
     */
    agentAuthPanelComponent?: ComponentType<AgentAuthPanelProps>;
};

type InputPanelProps = {
    title?: ReactNode;
    placeholder?: string;
    submitLabel?: ReactNode;
    skipLabel?: ReactNode;
    continueLabel?: ReactNode;
    contentComponent?: ComponentType<InputPanelContentProps>;
    actionsComponent?: ComponentType<InputActionsProps>;
    previousQuestionLabel?: string;
    nextQuestionLabel?: string;
    singleChoiceHint?: ReactNode;
    multiChoiceHint?: ReactNode;
    otherPlaceholder?: string;
    questionProgressLabel?: (current: number, total: number) => ReactNode;
};

type ApprovalPanelProps = {
    title?: ReactNode;
    approveLabel?: ReactNode;
    actionsComponent?: ComponentType<ApprovalActionsProps>;
};

type AgentAuthPanelProps = {
    title?: ReactNode;
    authorizationLabel?: ReactNode;
    deviceVerificationLabel?: ReactNode;
    resumeLabel?: ReactNode;
    deviceCodeLabel?: ReactNode;
    completedLabel?: ReactNode;
    authorizationDescription?: ReactNode;
    providerLabel?: ReactNode;
    linkButtonComponent?: ComponentType<AgentAuthLinkButtonProps>;
    resumeButtonComponent?: ComponentType<AgentAuthResumeButtonProps>;
};

type InputPanelContentProps = InputPanelContentComponentProps & {
    freeformContentComponent?: ComponentType<InputPanelContentComponentProps>;
    singleQuestionContentComponent?: ComponentType<InputPanelContentComponentProps>;
    structuredQuestionContentComponent?: ComponentType<InputPanelContentComponentProps>;
    wizardContentComponent?: ComponentType<InputPanelContentComponentProps>;
};

type InputPanelContentComponentProps = {
    toolInput: InputPanelContentState;
    placeholder?: string;
    otherPlaceholder?: string;
    singleChoiceHint?: ReactNode;
    multiChoiceHint?: ReactNode;
};

type InputActionsProps = {
    toolInput: InputPanelActionState;
    submitLabel?: ReactNode;
    skipLabel?: ReactNode;
    continueLabel?: ReactNode;
};

type ApprovalActionsProps = {
    approveLabel?: ReactNode;
};

type ApprovalSelectorProps = ComponentProps<SlotRenderer<ComposerSlotControls["approvalPolicy"]>> & {
    /** Optional labels for the trigger, title, and individual policies. */
    labels?: ApprovalSelectorLabels | undefined;
    triggerProps?: SelectionMenuProps["triggerProps"];
    /** Visual layout used by the trigger and menu. */
    layout?: SelectionMenuProps["layout"] | undefined;
};

type AgentAuthLinkButtonProps = {
    label?: ReactNode;
    authorizationUri?: string | undefined;
    disabled?: boolean | undefined;
    onOpen?: () => void;
};

type AgentAuthResumeButtonProps = {
    label?: ReactNode;
    submitting?: boolean | undefined;
    error?: Error | undefined;
    disabled?: boolean | undefined;
    onResume?: (() => void) | undefined;
};

type InputPanelContentState = Pick<ReturnType<typeof useToolInput>, "input" | "formState" | "formActions">;

type InputPanelActionState = Pick<ReturnType<typeof useToolInput>, "formState" | "formActions" | "skip" | "submitting" | "error">;

type ApprovalSelectorLabels = {
    trigger?: string;
    title?: string;
    options?: Partial<Record<ApprovalPolicy, {
        label?: string;
        description?: string;
    }>>;
};