@creaditor/cdtr-chat

Embeddable <cdtr-chat> web component. An abstract chat UI shell: it renders the transcript, captures user input, supports chip actions and file/voice input, and emits events. No transport coupling — the host wires submissions to whatever backend it likes (a custom REST endpoint, an LLM API, websockets, anything).

Built with Lit. Hebrew + English out of the box, with full RTL layout. Persists the transcript to localStorage so refreshes don't lose state.

Install

npm install @creaditor/cdtr-chat

Use

As an ES module

<cdtr-chat lang="en" header="Assistant" prompt="Ask me anything"></cdtr-chat>

<script type="module">
  import '@creaditor/cdtr-chat';

  const chat = document.querySelector('cdtr-chat');

  chat.addEventListener('cdtr-chat:submit', async (e) => {
    const { text } = e.detail;
    chat.busy = true;
    const reply = await myBackend.send(text);
    chat.appendMessage({ role: 'assistant', text: reply });
    chat.busy = false;
  });
</script>

Via CDN (UMD)

<script src="https://unpkg.com/@creaditor/cdtr-chat"></script>
<cdtr-chat></cdtr-chat>

Attributes

| Attribute | Type | Default | Description | | ------------- | ------- | ---------------------- | --------------------------------------------------------------------------- | | lang | string | "en" | "he" or "en". Auto-sets dir="rtl" for Hebrew. | | header | string | "" | Title shown in the chat header. | | greeting | string | "" | First-load greeting line (empty hides it). | | prompt | string | "" | Composer placeholder text. | | user-name | string | "" | Appended to the localized greeting, e.g. "Good afternoon, Dev". | | attachments | boolean | true | Show the attach-file button. | | accept | string | "" | Native <input accept> filter for file picker. | | voice | boolean | true | Show the speech-to-text button (browser SR API). | | closable | boolean | false | Render header expand + close buttons (for modal/sidebar chrome). | | menu | boolean | false | Make the title a button that emits cdtr-chat:menu. | | actions | JSON | [] | Action chips, e.g. '[{"id":"a","label":"Tighten"}]'. | | tags | JSON | [] | Scope tags echoed back in every submit / action detail. | | storage-key | string | "cdtr-chat:messages" | localStorage key for transcript persistence. Empty string disables. | | busy | boolean | false | Render the three-dot typing indicator. Reflected to the host element. | | loader-src | string | "" | Optional inline video URL used in place of the dots while busy. |

messages and actions can also be set as properties to pass non-string values (e.g. chat.messages = [...]).

Events

All events bubble and are composed. Names are prefixed with cdtr-chat:.

| Event | detail | When | | ---------------------- | ----------------------------------------- | ------------------------------------------------------------------- | | cdtr-chat:submit | { text, tags } | User submitted a message (enter or send button). | | cdtr-chat:action | { id, label, tags } | User clicked an action chip. | | cdtr-chat:card-click | { card } | User activated a ChatCard attached to an assistant message. | | cdtr-chat:new | — | User started a new chat (header button). | | cdtr-chat:add | — | User clicked the attach button. | | cdtr-chat:files | { files: File[] } | Files were chosen from the picker. | | cdtr-chat:voice | { state: 'start' \| 'stop' \| 'error' \| 'unsupported' } | Speech-recognition lifecycle. | | cdtr-chat:menu | — | Title button clicked (only when menu attr is set). | | cdtr-chat:expand | — | Expand button clicked (only when closable is set). | | cdtr-chat:close | — | Close button clicked (only when closable is set). | | cdtr-chat:hydrated | { session, social_posts, newsletters } | Window-level event fired after restoring a session. |

Methods

chat.appendMessage({ role: 'user' | 'assistant', text: string, card?: ChatCard });
chat.endAssistantStream(finalText?: string);   // finalize a streaming reply
chat.setActions(actions: ChatAction[]);        // replace the chip set

Types

type ChatRole = 'user' | 'assistant';

type ChatMessage = {
  id?: string;
  role: ChatRole;
  text: string;
  card?: ChatCard;
  ts?: number;
};

type ChatAction = { id: string; label: string };

type ChatCard = {
  kind: string;
  id: string;
  label: string;
  sublabel?: string;
};

Styling

The component exposes CSS custom properties for theming:

cdtr-chat {
  --cdtr-chat-bg: #ffffff;
  --cdtr-chat-fg: #111827;
  --cdtr-chat-muted: #6b7280;
  --cdtr-chat-accent: #7c3aed;
  --cdtr-chat-bubble-user: #ede9fe;
  --cdtr-chat-bubble-assistant: #f3f4f6;
}

License

MIT