@ai37/copilotkit-chat-helpers

Хелперы чат-уровня для CopilotKit v2: заворачивание A2UI-форм (activity-сообщений) в сворачиваемый аккордеон (во всём чате развёрнута максимум одна форма, последняя пришедшая открыта) и сворачивание длинных сообщений пользователя до ~6 строк (как в ChatGPT).

Пакет CopilotKit-agnostic: обёртка типизирована структурно ({ render: ComponentType }), зависимость только peer react.

Установка

npm i @ai37/copilotkit-chat-helpers

Требования к консюмеру

1. Tailwind CSS + shadcn-токены. CollapsibleForm стилизован Tailwind-утилитами (border-border, px-3 py-2, …); токен --border должен быть определён в теме приложения (shadcn-стиль).

2. Скан пакета Tailwind-билдом. Tailwind по умолчанию не сканирует node_modules — без этого классы выпадут из билда. Tailwind v4 (в css):

   @source "../node_modules/@ai37/copilotkit-chat-helpers";

Использование

import {
  CopilotKitProvider,
  createA2UIMessageRenderer,
} from "@copilotkit/react-core/v2"
import {
  FormAccordionProvider,
  createCollapsibleA2uiRenderer,
} from "@ai37/copilotkit-chat-helpers"

const a2uiRenderer = createA2UIMessageRenderer({ theme, catalog })

// Стабильная ссылка — CopilotKit требует не пересоздавать массив на каждом рендере.
const renderActivityMessages = [createCollapsibleA2uiRenderer(a2uiRenderer)]

export function Providers({ children }) {
  return (
    <CopilotKitProvider renderActivityMessages={renderActivityMessages}>
      <FormAccordionProvider>{children}</FormAccordionProvider>
    </CopilotKitProvider>
  )
}

API

• createCollapsibleA2uiRenderer(base, options?) — оборачивает renderer из createA2UIMessageRenderer: переопределяет только render (обёртка в CollapsibleForm по message.id), activityType/content наследуются. Заголовок аккордеона берётся из данных агента: title первого компонента в операциях A2UI (у FormCard/ChoiceCard обязателен по схеме каталога). Пока операций нет (стрим) или title отсутствует — фолбэк options.title (по умолчанию "Форма").

• extractA2uiTitle(operations) — сам извлекатель заголовка из операций A2UI v0.9 (content.a2ui_operations); undefined, если titled-компонента нет.

• FormAccordionProvider / useFormAccordion — стейт аккордеона (openId/register/toggle): новая форма открывается, прежние сворачиваются; ручной toggle переживает перерендер.

• CollapsibleForm — сворачиваемая обёртка (можно использовать напрямую вне A2UI-сценария).

• createCollapsibleUserMessageRenderer(options) — фабрика messageRenderer для слота chatView.messageView.userMessage: сообщения пользователя выше порога (collapsedMaxHeightPx, по умолчанию 192px ≈ 6 строк, + гистерезис hysteresisPx 42px ≈ 1.5 строки) клипаются max-height с alpha-маской и кнопкой «Развернуть»/«Свернуть» (aria-expanded; лейблы настраиваются). Контент остаётся в DOM (Cmd+F, выделение); порог в px, не в символах — пересчитывается по scrollHeight через ResizeObserver при ресайзе. Дефолтный рендерер пузыря передаётся опцией messageRenderer (обычно CopilotChatUserMessage.MessageRenderer) — CopilotKit не в зависимостях пакета:

  import { CopilotChatUserMessage } from "@copilotkit/react-core/v2"
  import { createCollapsibleUserMessageRenderer } from "@ai37/copilotkit-chat-helpers"
  
  const CollapsibleUserMessage = createCollapsibleUserMessageRenderer({
    messageRenderer: CopilotChatUserMessage.MessageRenderer,
  })
  
  // <CopilotChat chatView={{ messageView: { userMessage: { messageRenderer: CollapsibleUserMessage } } }} />