@kitn.ai/ui 0.14.1 → 0.15.1

package/src/stories/examples/usage/streaming-response.ts

@@ -1,687 +0,0 @@
-import type { ExampleUsage, StoryUsage } from './types';
-
-// Shared streamed reply used across the snippets (trimmed from the demo).
-const STREAM =
-  'Server-Sent Events (SSE) are a lightweight alternative to WebSockets for one-way server-to-client streaming. Use SSE when you only need server push.';
-
-/** Typewriter Streaming — reveal the reply character by character. */
-const typewriter: StoryUsage = {
-  intro:
-    'Reveal an assistant reply character by character. Set the `text` property to a string (or an `AsyncIterable<string>` assigned as a JS property — async iterables cannot be HTML attributes) with `mode="typewriter"` and handle `kai-complete` to unlock the input once all characters are displayed. **Cancel gotcha:** there is no built-in `stop()` — abort your own fetch with an `AbortController` and then clear your streaming state. **Replay gotcha:** passing the same string value again does not re-run the animation; unmount and remount the element instead.',
-  snippets: {
-    html: `<!-- Register the elements once (CDN or bundler) -->
-<script type="module">
-  import 'https://cdn.jsdelivr.net/npm/@kitn.ai/ui/dist/kitn-chat.es.js';
-</script>
-
-<kai-response-stream id="stream" mode="typewriter" speed="40"></kai-response-stream>
-
-<script type="module">
-  const stream = document.getElementById('stream');
-  // A plain string is fine as a property; an AsyncIterable<string> MUST be a property.
-  stream.text = '${STREAM}';
-  stream.addEventListener('kai-complete', () => console.log('done streaming'));
-</script>`,
-
-    react: `import { ResponseStream } from '@kitn.ai/ui/react';
-
-export function StreamedReply() {
-  return (
-    <ResponseStream
-      text="${STREAM}"
-      mode="typewriter"
-      speed={40}
-      onComplete={() => console.log('done streaming')}
-    />
-  );
-}`,
-
-    vue: `<script setup>
-import '@kitn.ai/ui/elements'; // register once (e.g. in main.ts)
-
-// A string can be a plain attr; an AsyncIterable must be bound as a property.
-const text = '${STREAM}';
-
-function onComplete() {
-  console.log('done streaming');
-}
-</script>
-
-<template>
-  <kai-response-stream
-    :text.prop="text"
-    mode="typewriter"
-    :speed="40"
-    @kai-complete="onComplete"
-  />
-</template>`,
-
-    svelte: `<script>
-  import '@kitn.ai/ui/elements';
-
-  let el;
-  const text = '${STREAM}';
-  $: if (el) el.text = text; // AsyncIterable values are set as properties
-
-  function onComplete() {
-    console.log('done streaming');
-  }
-</script>
-
-<kai-response-stream
-  bind:this={el}
-  mode="typewriter"
-  speed="40"
-  on:kai-complete={onComplete}
-/>`,
-
-    angular: `// main.ts: import '@kitn.ai/ui/elements' before bootstrapApplication,
-// and add CUSTOM_ELEMENTS_SCHEMA to the component.
-import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
-
-@Component({
-  selector: 'app-stream',
-  standalone: true,
-  schemas: [CUSTOM_ELEMENTS_SCHEMA],
-  template: \`
-    <kai-response-stream
-      [text]="text"
-      mode="typewriter"
-      [speed]="40"
-      (kai-complete)="onComplete()"
-    ></kai-response-stream>
-  \`,
-})
-export class StreamComponent {
-  text = '${STREAM}';
-  onComplete() {
-    console.log('done streaming');
-  }
-}`,
-
-    solid: `import { createSignal, Show } from 'solid-js';
-import { Message, MessageAvatar, ResponseStream } from '@kitn.ai/ui';
-
-export function StreamedReply() {
-  const [streaming, setStreaming] = createSignal(true);
-  return (
-    <Show when={streaming()}>
-      <Message>
-        <MessageAvatar fallback="AI" alt="Assistant" />
-        <div class="flex-1 rounded-lg p-2 bg-secondary">
-          <ResponseStream
-            textStream="${STREAM}"
-            mode="typewriter"
-            speed={40}
-            onComplete={() => setStreaming(false)}
-            class="prose dark:prose-invert prose-sm max-w-none"
-          />
-        </div>
-      </Message>
-    </Show>
-  );
-}`,
-  },
-};
-
-/**
- * Waiting for First Token — the "thinking" state before any token arrives.
- * This story does NOT stream: there's nothing for kai-response-stream to do yet,
- * so the snippets show the loading primitives that precede a stream.
- */
-const waiting: StoryUsage = {
-  intro:
-    'Show a placeholder **before the first token arrives** — `<kai-response-stream>` is not involved yet (there is nothing to stream). Use `<kai-loader variant="dots">` for the thinking spinner and `<kai-text-shimmer>` for the shimmering label. Once the first chunk arrives, swap them out for `<kai-response-stream>`. Use `<kai-loader variant="typing">` in the input bar to signal that tokens are now *flowing* — `dots` means waiting, `typing` means actively generating.',
-  snippets: {
-    html: `<script type="module">
-  import 'https://cdn.jsdelivr.net/npm/@kitn.ai/ui/dist/kitn-chat.es.js';
-</script>
-
-<div style="display:flex;align-items:center;gap:0.75rem">
-  <kai-loader variant="dots" size="sm"></kai-loader>
-  <kai-text-shimmer>Thinking...</kai-text-shimmer>
-</div>`,
-
-    react: `import { Loader, TextShimmer } from '@kitn.ai/ui/react';
-
-<div className="flex items-center gap-3">
-  <Loader variant="dots" size="sm" />
-  <TextShimmer>Thinking...</TextShimmer>
-</div>`,
-
-    vue: `<script setup>
-import '@kitn.ai/ui/elements';
-</script>
-
-<template>
-  <div style="display:flex;align-items:center;gap:0.75rem">
-    <kai-loader variant="dots" size="sm" />
-    <kai-text-shimmer>Thinking...</kai-text-shimmer>
-  </div>
-</template>`,
-
-    svelte: `<script>
-  import '@kitn.ai/ui/elements';
-</script>
-
-<div style="display:flex;align-items:center;gap:0.75rem">
-  <kai-loader variant="dots" size="sm" />
-  <kai-text-shimmer>Thinking...</kai-text-shimmer>
-</div>`,
-
-    angular: `import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
-
-@Component({
-  selector: 'app-waiting',
-  standalone: true,
-  schemas: [CUSTOM_ELEMENTS_SCHEMA],
-  template: \`
-    <div style="display:flex;align-items:center;gap:0.75rem">
-      <kai-loader variant="dots" size="sm"></kai-loader>
-      <kai-text-shimmer>Thinking...</kai-text-shimmer>
-    </div>
-  \`,
-})
-export class WaitingComponent {}`,
-
-    solid: `import { Message, MessageAvatar, Loader, TextShimmer } from '@kitn.ai/ui';
-
-export function Thinking() {
-  return (
-    <Message>
-      <MessageAvatar fallback="AI" alt="Assistant" />
-      <div class="flex-1 flex items-center gap-3 rounded-lg p-3 bg-secondary">
-        <Loader variant="dots" size="sm" />
-        <TextShimmer class="text-sm">Thinking...</TextShimmer>
-      </div>
-    </Message>
-  );
-}`,
-  },
-};
-
-/** Fade-in Streaming — words fade in instead of appearing char by char. */
-const fade: StoryUsage = {
-  intro:
-    'Reveal the reply word-by-word with staggered CSS fade-ins instead of a typewriter. Set `mode="fade"` on `<kai-response-stream>` and tune `speed` to control the stagger cadence. **Important:** when `text` is a plain string, `kai-complete` / `onComplete` is **never fired** in fade mode — all segments are delivered immediately and CSS handles the reveal with no detectable endpoint. If you need a completion callback in fade mode, pass an `AsyncIterable<string>` as a property instead (the callback fires after the iterator is exhausted).',
-  snippets: {
-    html: `<script type="module">
-  import 'https://cdn.jsdelivr.net/npm/@kitn.ai/ui/dist/kitn-chat.es.js';
-</script>
-
-<kai-response-stream id="stream" mode="fade" speed="30"></kai-response-stream>
-
-<script type="module">
-  const stream = document.getElementById('stream');
-  stream.text = '${STREAM}';
-  stream.addEventListener('kai-complete', () => console.log('done streaming'));
-</script>`,
-
-    react: `import { ResponseStream } from '@kitn.ai/ui/react';
-
-<ResponseStream
-  text="${STREAM}"
-  mode="fade"
-  speed={30}
-  onComplete={() => console.log('done streaming')}
-/>`,
-
-    vue: `<script setup>
-import '@kitn.ai/ui/elements';
-const text = '${STREAM}';
-</script>
-
-<template>
-  <kai-response-stream
-    :text.prop="text"
-    mode="fade"
-    :speed="30"
-    @kai-complete="() => console.log('done streaming')"
-  />
-</template>`,
-
-    svelte: `<script>
-  import '@kitn.ai/ui/elements';
-  let el;
-  const text = '${STREAM}';
-  $: if (el) el.text = text;
-</script>
-
-<kai-response-stream
-  bind:this={el}
-  mode="fade"
-  speed="30"
-  on:kai-complete={() => console.log('done streaming')}
-/>`,
-
-    angular: `import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
-
-@Component({
-  selector: 'app-stream',
-  standalone: true,
-  schemas: [CUSTOM_ELEMENTS_SCHEMA],
-  template: \`
-    <kai-response-stream
-      [text]="text"
-      mode="fade"
-      [speed]="30"
-      (kai-complete)="log()"
-    ></kai-response-stream>
-  \`,
-})
-export class StreamComponent {
-  text = '${STREAM}';
-  log() { console.log('done streaming'); }
-}`,
-
-    solid: `import { createSignal, Show } from 'solid-js';
-import { Message, MessageAvatar, ResponseStream } from '@kitn.ai/ui';
-
-export function FadeReply() {
-  const [streaming, setStreaming] = createSignal(true);
-  return (
-    <Show when={streaming()}>
-      <Message>
-        <MessageAvatar fallback="AI" alt="Assistant" />
-        <div class="flex-1 rounded-lg p-2 bg-secondary">
-          <ResponseStream
-            textStream="${STREAM}"
-            mode="fade"
-            speed={30}
-            onComplete={() => setStreaming(false)}
-            class="prose dark:prose-invert prose-sm max-w-none"
-          />
-        </div>
-      </Message>
-    </Show>
-  );
-}`,
-  },
-};
-
-/** Full Streaming Lifecycle — idle → waiting → streaming → complete in one interactive story. */
-const fullLifecycle: StoryUsage = {
-  intro:
-    'All three phases in one interactive story: **waiting** (dots loader + shimmer before first token), **streaming** (typewriter reveal with a stop button), and **complete** (action bar appears; input unlocks). This is the pattern to follow in production. **Phase ownership:** `ResponseStream` / `kai-response-stream` knows nothing about waiting or cancellation — your app owns a `phase` signal and drives the UI from it. **No built-in cancel:** to stop mid-stream, call `abortController.abort()` on your own fetch and then reset your phase state; the element will stop receiving characters but does not reset its display.',
-  snippets: {
-    html: `<script type="module">
-  import 'https://cdn.jsdelivr.net/npm/@kitn.ai/ui/dist/kitn-chat.es.js';
-</script>
-
-<!-- Phase 1: Waiting -->
-<div id="waiting" style="display:flex;align-items:center;gap:0.75rem">
-  <kai-loader variant="dots" size="sm"></kai-loader>
-  <kai-text-shimmer>Thinking...</kai-text-shimmer>
-</div>
-
-<!-- Phase 2+3: Streaming → Complete (hidden initially) -->
-<div id="reply" hidden>
-  <kai-response-stream id="stream" mode="typewriter" speed="35"></kai-response-stream>
-  <!-- Action bar, shown after complete -->
-  <div id="actions" hidden>
-    <button id="copy-btn">Copy</button>
-    <button id="regen-btn">Regenerate</button>
-  </div>
-</div>
-
-<script type="module">
-  const controller = new AbortController();
-
-  // Simulate: after ~1.2 s first token arrives
-  setTimeout(() => {
-    document.getElementById('waiting').hidden = true;
-    document.getElementById('reply').hidden = false;
-
-    const stream = document.getElementById('stream');
-    // Pass a plain string; or assign an AsyncIterable<string> as a property.
-    stream.text = '${STREAM}';
-    stream.addEventListener('kai-complete', () => {
-      document.getElementById('actions').hidden = false;
-    });
-  }, 1200);
-
-  document.getElementById('stop-btn')?.addEventListener('click', () => {
-    controller.abort();          // cancel the real fetch
-    document.getElementById('waiting').hidden = true; // or reset your phase
-  });
-</script>`,
-
-    react: `import { useState, useEffect, useRef } from 'react';
-import { ResponseStream, Loader, TextShimmer } from '@kitn.ai/ui/react';
-
-type Phase = 'idle' | 'waiting' | 'streaming' | 'complete';
-
-export function StreamingChat() {
-  const [phase, setPhase] = useState<Phase>('idle');
-  const [mounted, setMounted] = useState(false);
-  const controllerRef = useRef<AbortController | null>(null);
-
-  const handleSend = () => {
-    controllerRef.current = new AbortController();
-    setMounted(false);
-    setPhase('waiting');
-    // Simulate latency before first token
-    setTimeout(() => { setMounted(true); setPhase('streaming'); }, 1200);
-  };
-
-  const handleStop = () => {
-    controllerRef.current?.abort();
-    setMounted(false);
-    setPhase('idle');
-  };
-
-  return (
-    <div>
-      {phase === 'waiting' && (
-        <div className="flex items-center gap-3">
-          <Loader variant="dots" size="sm" />
-          <TextShimmer>Thinking...</TextShimmer>
-        </div>
-      )}
-      {mounted && (
-        <ResponseStream
-          text="${STREAM}"
-          mode="typewriter"
-          speed={35}
-          onComplete={() => setPhase('complete')}
-        />
-      )}
-      {phase === 'complete' && <div>✓ Action bar here</div>}
-      <button onClick={phase === 'idle' || phase === 'complete' ? handleSend : handleStop}>
-        {phase === 'idle' || phase === 'complete' ? 'Send' : 'Stop'}
-      </button>
-    </div>
-  );
-}`,
-
-    vue: `<script setup>
-import { ref } from 'vue';
-import '@kitn.ai/ui/elements';
-
-const REPLY = '${STREAM}';
-const phase = ref('idle'); // 'idle' | 'waiting' | 'streaming' | 'complete'
-const mounted = ref(false);
-let controller = null;
-
-function send() {
-  controller = new AbortController();
-  mounted.value = false;
-  phase.value = 'waiting';
-  setTimeout(() => { mounted.value = true; phase.value = 'streaming'; }, 1200);
-}
-
-function stop() {
-  controller?.abort();
-  mounted.value = false;
-  phase.value = 'idle';
-}
-
-function onComplete() { phase.value = 'complete'; }
-</script>
-
-<template>
-  <div>
-    <div v-if="phase === 'waiting'" style="display:flex;align-items:center;gap:0.75rem">
-      <kai-loader variant="dots" size="sm" />
-      <kai-text-shimmer>Thinking...</kai-text-shimmer>
-    </div>
-
-    <kai-response-stream
-      v-if="mounted"
-      :text.prop="REPLY"
-      mode="typewriter"
-      :speed="35"
-      @kai-complete="onComplete"
-    />
-
-    <div v-if="phase === 'complete'">✓ Action bar here</div>
-
-    <button @click="phase === 'idle' || phase === 'complete' ? send() : stop()">
-      {{ phase === 'idle' || phase === 'complete' ? 'Send' : 'Stop' }}
-    </button>
-  </div>
-</template>`,
-
-    svelte: `<script>
-  import '@kitn.ai/ui/elements';
-
-  const REPLY = '${STREAM}';
-  let phase = 'idle'; // 'idle' | 'waiting' | 'streaming' | 'complete'
-  let mounted = false;
-  let el;
-  let controller;
-
-  $: if (el && mounted) el.text = REPLY;
-
-  function send() {
-    controller = new AbortController();
-    mounted = false;
-    phase = 'waiting';
-    setTimeout(() => { mounted = true; phase = 'streaming'; }, 1200);
-  }
-
-  function stop() {
-    controller?.abort();
-    mounted = false;
-    phase = 'idle';
-  }
-
-  function onComplete() { phase = 'complete'; }
-</script>
-
-{#if phase === 'waiting'}
-  <div style="display:flex;align-items:center;gap:0.75rem">
-    <kai-loader variant="dots" size="sm" />
-    <kai-text-shimmer>Thinking...</kai-text-shimmer>
-  </div>
-{/if}
-
-{#if mounted}
-  <kai-response-stream
-    bind:this={el}
-    mode="typewriter"
-    speed="35"
-    on:kai-complete={onComplete}
-  />
-{/if}
-
-{#if phase === 'complete'}<div>✓ Action bar here</div>{/if}
-
-<button on:click={phase === 'idle' || phase === 'complete' ? send : stop}>
-  {phase === 'idle' || phase === 'complete' ? 'Send' : 'Stop'}
-</button>`,
-
-    angular: `import { Component, signal, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
-
-type Phase = 'idle' | 'waiting' | 'streaming' | 'complete';
-
-@Component({
-  selector: 'app-streaming-chat',
-  standalone: true,
-  schemas: [CUSTOM_ELEMENTS_SCHEMA],
-  template: \`
-    <div *ngIf="phase() === 'waiting'" style="display:flex;align-items:center;gap:0.75rem">
-      <kai-loader variant="dots" size="sm"></kai-loader>
-      <kai-text-shimmer>Thinking...</kai-text-shimmer>
-    </div>
-
-    <kai-response-stream
-      *ngIf="mounted()"
-      [text]="reply"
-      mode="typewriter"
-      [speed]="35"
-      (kai-complete)="onComplete()">
-    </kai-response-stream>
-
-    <div *ngIf="phase() === 'complete'">✓ Action bar here</div>
-
-    <button (click)="toggle()">
-      {{ phase() === 'idle' || phase() === 'complete' ? 'Send' : 'Stop' }}
-    </button>
-  \`,
-})
-export class StreamingChatComponent {
-  reply = '${STREAM}';
-  phase = signal<Phase>('idle');
-  mounted = signal(false);
-  private controller: AbortController | null = null;
-
-  toggle() {
-    if (this.phase() === 'idle' || this.phase() === 'complete') this.send();
-    else this.stop();
-  }
-
-  send() {
-    this.controller = new AbortController();
-    this.mounted.set(false);
-    this.phase.set('waiting');
-    setTimeout(() => { this.mounted.set(true); this.phase.set('streaming'); }, 1200);
-  }
-
-  stop() {
-    this.controller?.abort();
-    this.mounted.set(false);
-    this.phase.set('idle');
-  }
-
-  onComplete() { this.phase.set('complete'); }
-}`,
-
-    solid: `import { createSignal, Show } from 'solid-js';
-import {
-  ChatContainer, ChatContainerContent, ChatContainerScrollAnchor,
-  Message, MessageAvatar, MessageContent, MessageActions,
-  PromptInput, PromptInputTextarea, PromptInputActions,
-  ResponseStream, Loader, TextShimmer, Button,
-} from '@kitn.ai/ui';
-import { Square, ArrowUp, Copy, RefreshCw } from 'lucide-solid';
-
-type Phase = 'idle' | 'waiting' | 'streaming' | 'complete';
-
-const REPLY = '${STREAM}';
-
-export function StreamingLifecycle() {
-  const [phase, setPhase] = createSignal<Phase>('idle');
-  const [showStream, setShowStream] = createSignal(false);
-  let controller: AbortController | undefined;
-
-  const handleSend = () => {
-    controller = new AbortController();
-    setShowStream(false);
-    setPhase('waiting');
-    // Simulate latency; in production replace with a real fetch:
-    // const res = await fetch('/api/chat', { signal: controller.signal });
-    setTimeout(() => { setShowStream(true); setPhase('streaming'); }, 1200);
-  };
-
-  const handleStop = () => {
-    controller?.abort();   // cancel the real fetch
-    setShowStream(false);  // unmounts ResponseStream, stopping character reveals
-    setPhase('idle');
-  };
-
-  return (
-    <div class="flex flex-col h-[640px] w-full max-w-2xl bg-background rounded-xl shadow-lg overflow-hidden">
-      <ChatContainer class="flex-1 p-4">
-        <ChatContainerContent class="space-y-6 py-4">
-
-          {/* Phase 1 — Waiting */}
-          <Show when={phase() === 'waiting'}>
-            <Message>
-              <MessageAvatar fallback="AI" alt="Assistant" />
-              <div class="flex-1 flex items-center gap-3 rounded-lg p-3 bg-secondary">
-                <Loader variant="dots" size="sm" />
-                <TextShimmer class="text-sm">Thinking...</TextShimmer>
-              </div>
-            </Message>
-          </Show>
-
-          {/* Phase 2+3 — Streaming → Complete */}
-          <Show when={showStream()}>
-            <Message>
-              <MessageAvatar fallback="AI" alt="Assistant" />
-              <div class="flex-1 space-y-2">
-                <div class="rounded-lg p-2 bg-secondary">
-                  <ResponseStream
-                    textStream={REPLY}
-                    mode="typewriter"
-                    speed={35}
-                    onComplete={() => setPhase('complete')}
-                    class="prose dark:prose-invert prose-sm max-w-none"
-                  />
-                </div>
-                {/* Action bar only after onComplete fires */}
-                <Show when={phase() === 'complete'}>
-                  <MessageActions>
-                    <Button variant="ghost" size="icon-sm" aria-label="Copy message">
-                      <Copy class="size-3.5" />
-                    </Button>
-                    <Button variant="ghost" size="icon-sm" aria-label="Regenerate" onClick={handleSend}>
-                      <RefreshCw class="size-3.5" />
-                    </Button>
-                  </MessageActions>
-                </Show>
-              </div>
-            </Message>
-          </Show>
-
-          <ChatContainerScrollAnchor />
-        </ChatContainerContent>
-      </ChatContainer>
-
-      <div class="px-4 pb-4">
-        <Show
-          when={phase() === 'idle' || phase() === 'complete'}
-          fallback={
-            <PromptInput disabled isLoading>
-              <PromptInputTextarea placeholder={phase() === 'waiting' ? 'Waiting for first token...' : 'Generating...'} />
-              <PromptInputActions class="justify-between">
-                <div class="flex items-center gap-2">
-                  <Show when={phase() === 'streaming'} fallback={<Loader variant="dots" size="sm" />}>
-                    <Loader variant="typing" size="sm" />
-                  </Show>
-                  <span class="text-xs text-muted-foreground">
-                    {phase() === 'waiting' ? 'Waiting for response...' : 'Streaming response...'}
-                  </span>
-                </div>
-                <Button variant="outline" size="icon-sm" class="rounded-full" onClick={handleStop} aria-label="Stop generation">
-                  <Square class="size-3" />
-                </Button>
-              </PromptInputActions>
-            </PromptInput>
-          }
-        >
-          <PromptInput onSubmit={handleSend}>
-            <PromptInputTextarea placeholder="Send to start the lifecycle..." />
-            <PromptInputActions class="justify-end">
-              <Button variant="default" size="icon-sm" class="rounded-full" onClick={handleSend} aria-label="Send">
-                <ArrowUp class="size-4" />
-              </Button>
-            </PromptInputActions>
-          </PromptInput>
-        </Show>
-      </div>
-    </div>
-  );
-}`,
-  },
-};
-
-/**
- * Example: Streaming Response — a typewriter / fade reveal of an assistant
- * reply, plus the "thinking" state before the first token. Per-story: the
- * Usage tab shows the snippet for the story you're on; the example-level fields
- * below are the fallback.
- */
-const streamingResponse: ExampleUsage = {
-  title: 'Examples/Streaming Response',
-  ...typewriter, // example-level fallback = the headline "Typewriter Streaming"
-  stories: {
-    'Typewriter Streaming': typewriter,
-    'Waiting for First Token': waiting,
-    'Fade-in Streaming': fade,
-    'Full Streaming Lifecycle': fullLifecycle,
-  },
-};
-
-export default streamingResponse;