Klarhimmel UI

App, assistant thread

App, assistant thread preview

Install

npx shadcn add @klarhimmel/app-assistant-thread

Usage

import { Theme } from '@/components/klarhimmel/theme/style';
import { BlockSurface } from '@/components/klarhimmel/blocks/surface';
import AppAssistantThread from '@/components/klarhimmel/blocks/app-assistant-thread';

export default function Section() {
  return (
    <Theme theme="brand">
      <BlockSurface>
        <AppAssistantThread props={{
          "label": "Conversation with the booking assistant",
          "state": "idle",
          "height": "auto",
          "userName": "You",
          "assistantName": "Booking assistant",
          "turns": [
            {
              "role": "user",
              "text": "Which double rooms are free on 14 and 15 November?"
            },
            {
              "role": "assistant",
              "text": "Two double rooms are free both nights at Exempelhotellet.\nRoom 204 faces the courtyard. Room 311 has a balcony and a bath.",
              "code": "204  Double, courtyard   1 190 SEK\n311  Double, balcony     1 490 SEK"
            },
            {
              "role": "user",
              "text": "Hold 311 for the Lindqvist family until Friday."
            }
          ],
          "codeLabel": "Code",
          "typing": "Writing…",
          "error": {
            "title": "The answer did not arrive",
            "message": "The connection dropped before the assistant finished. Your message is saved.",
            "retry": "Try again"
          },
          "empty": {
            "title": "Ask about rooms, rates or bookings",
            "hint": "The assistant can look things up and prepare changes. It asks before it changes anything.",
            "suggestions": [
              "Which rooms are free this weekend?",
              "Summarise today's arrivals",
              "Move booking 4821 to the 16th"
            ]
          }
        }} />
      </BlockSurface>
    </Theme>
  );
}

Install

Import

import Block from '@/components/klarhimmel/blocks/app-assistant-thread';
Also called
  • app/assistant-thread
About
A conversation with an assistant: user and assistant turns, optional code and four states. A log region; each turn is named by its speaker. The state, height and fixed scroll options are props.
Category
Interface sections for signed-in products.

Notes

When to use it

The message log of an assistant: user and assistant turns, optional code, and idle, streaming, error and empty states. Use `app-assistant-showcase` when you only want a picture of a conversation on a landing page.

Writing for it

- Each turn takes `text` up to 4000 characters and an optional `code` up to 20000. Put commands and file contents in `code` so they get their own scrollable, labelled region instead of running into the prose. - Names matter: `userName` and `assistantName` (30 characters) name each turn for a screen reader, and the user's avatar shows the first letter of the name. - For the empty state, give up to 3 `suggestions` of 80 characters as full questions someone would actually ask, since each becomes a button.

Watch out for

With `height` set to fixed the log scrolls inside the block at about 28rem and takes focus from the keyboard, so a fixed thread inside a page with other scrolling content can trap people. Suggestion and Retry buttons do nothing until a host passes handlers.

Usage

The block in a page, with its default content (long lists shortened). Every prop is in the table below.

section.tsx
import { Theme } from '@/components/klarhimmel/theme/style';
import { BlockSurface } from '@/components/klarhimmel/blocks/surface';
import AppAssistantThread from '@/components/klarhimmel/blocks/app-assistant-thread';

export default function Section() {
  return (
    <Theme theme="brand">
      <BlockSurface>
        <AppAssistantThread props={{
          "label": "Conversation with the booking assistant",
          "state": "idle",
          "height": "auto",
          "codeLabel": "Code",
          "userName": "You",
          "assistantName": "Booking assistant",
          "turns": [
            {
              "role": "user",
              "text": "Which double rooms are free on 14 and 15 November?"
            },
            {
              "role": "assistant",
              "text": "Two double rooms are free both nights at Exempelhotellet.\nRoom 204 faces the courtyard. Room 311 has a balcony and a bath.",
              "code": "204  Double, courtyard   1 190 SEK\n311  Double, balcony     1 490 SEK"
            },
            {
              "role": "user",
              "text": "Hold 311 for the Lindqvist family until Friday."
            }
          ],
          "typing": "Writing…",
          "error": {
            "title": "The answer did not arrive",
            "message": "The connection dropped before the assistant finished. Your message is saved.",
            "retry": "Try again"
          },
          "empty": {
            "title": "Ask about rooms, rates or bookings",
            "hint": "The assistant can look things up and prepare changes. It asks before it changes anything.",
            "suggestions": [
              "Which rooms are free this weekend?",
              "Summarise today's arrivals",
              "Move booking 4821 to the 16th"
            ]
          }
        }} />
      </BlockSurface>
    </Theme>
  );
}

Props

The type, default and text limit of every prop. On a real page, over-limit text is kept and checkSections flags it (Installation, Check a page before you ship); this live preview shows the default until it fits. The panel above edits all props.

PropTypeDefaultDescription
labelstring'Conversation with the booking assis…'Text, up to 60 characters.
state'idle' | 'streaming' | 'error' | 'empty''idle'One of 'idle', 'streaming', 'error', 'empty'.
height'auto' | 'fixed''auto'One of 'auto', 'fixed'.
userNamestring'You'Text, up to 30 characters.
assistantNamestring'Booking assistant'Text, up to 30 characters.
turns{ role, text, code }[]3 itemsList of up to 50. Each item: role ('user' | 'assistant'), text, code (optional).
codeLabelstring'Code'Text, up to 30 characters.
typingstring'Writing…'Text, up to 40 characters.
error{ title, message, retry }{…}Fields: title, message, retry.
empty{ title, hint, suggestions }{…}Fields: title, hint, suggestions.