@kitnai/chat 0.3.0 → 0.4.0

package/src/elements/kitn-model-switcher.stories.tsx

@@ -0,0 +1,80 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount } from 'solid-js';
+import './register'; // side effect: registers the custom elements
+import type { ModelOption } from '../types';
+
+// The web components are custom DOM elements, so declare the tags for JSX.
+declare module 'solid-js' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace JSX {
+    interface IntrinsicElements {
+      'kitn-model-switcher': JSX.HTMLAttributes<HTMLElement>;
+    }
+  }
+}
+
+const models: ModelOption[] = [
+  { id: 'opus', name: 'Claude Opus', provider: 'Anthropic' },
+  { id: 'sonnet', name: 'Claude Sonnet', provider: 'Anthropic' },
+  { id: 'haiku', name: 'Claude Haiku', provider: 'Anthropic' },
+];
+
+/** Render `<kitn-model-switcher>` with `models` set as a property; tracks selection. */
+function SwitcherElement(props: { models: ModelOption[]; current?: string }) {
+  let el: (HTMLElement & { models?: ModelOption[]; currentModel?: string }) | undefined;
+  onMount(() => {
+    if (!el) return;
+    el.models = props.models;
+    el.currentModel = props.current ?? props.models[0]?.id;
+    // reflect the selection back so the trigger label updates
+    el.addEventListener('modelchange', (e) => {
+      const ev = e as CustomEvent<{ modelId: string }>;
+      el!.currentModel = ev.detail.modelId;
+    });
+  });
+  return (
+    <kitn-model-switcher ref={(e) => (el = e as HTMLElement)} style={{ display: 'inline-block', padding: '40px' }} />
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-model-switcher id="ms"></kitn-model-switcher>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  const ms = document.getElementById('ms');
+  ms.models = [
+    { id: 'opus', name: 'Claude Opus', provider: 'Anthropic' },
+    { id: 'sonnet', name: 'Claude Sonnet', provider: 'Anthropic' },
+  ];
+  ms.currentModel = 'opus';
+  ms.addEventListener('modelchange', (e) => { ms.currentModel = e.detail.modelId; });
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-model-switcher',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-model-switcher>` is the framework-agnostic **web component** for picking the active model — a dropdown showing each model\'s name and provider — isolated in **Shadow DOM**. It mirrors the switcher inside `<kitn-chat>` as a standalone, composable piece.',
+          '**When to use:** building your own chat header and want the model picker on its own. In SolidJS, use the `ModelSwitcher` primitive.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, set the `models` **property** (and optionally `currentModel`), and listen for the `modelchange` **CustomEvent**. Note: like the underlying primitive, it only renders when more than one model is provided.",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** A three-model picker; selecting updates the trigger label. */
+export const Default: Story = {
+  render: () => <SwitcherElement models={models} current="opus" />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};

package/src/elements/kitn-prompt-input.stories.tsx

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { onMount } from 'solid-js';
 import './register'; // side effect: registers <kitn-chat>, <kitn-conversation-list>, <kitn-prompt-input>
+import type { AttachmentData } from '../components/attachments';
 
 // The web components are custom DOM elements, so declare the tags for JSX.
 declare module 'solid-js' {
@@ -18,26 +19,43 @@ const sampleSuggestions: string[] = [
   'Explain like I am five',
 ];
 
+function imgData(fill: string, glyph: string) {
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="96" height="96"><rect width="96" height="96" rx="12" fill="${fill}"/><text x="48" y="60" font-size="42" text-anchor="middle" fill="white">${glyph}</text></svg>`;
+  return 'data:image/svg+xml;utf8,' + encodeURIComponent(svg);
+}
+
+const sampleAttachments: AttachmentData[] = [
+  { id: 'a1', type: 'file', filename: 'architecture.png', mediaType: 'image/png', url: imgData('#7c3aed', '◆') },
+  { id: 'a2', type: 'file', filename: 'spec.pdf', mediaType: 'application/pdf' },
+];
+
+interface PromptInputEl extends HTMLElement {
+  value?: string;
+  placeholder?: string;
+  disabled?: boolean;
+  loading?: boolean;
+  suggestions?: string[];
+  search?: boolean;
+  voice?: boolean;
+  attachments?: AttachmentData[];
+}
+
 /** Live demo of the actual `<kitn-prompt-input>` custom element (Shadow DOM and all). */
-function PromptInputElement() {
-  let el:
-    | (HTMLElement & {
-        value?: string;
-        placeholder?: string;
-        disabled?: boolean;
-        loading?: boolean;
-        suggestions?: string[];
-      })
-    | undefined;
+function PromptInputElement(props?: { search?: boolean; voice?: boolean; attachments?: AttachmentData[] }) {
+  let el: PromptInputEl | undefined;
   onMount(() => {
-    if (el) {
-      el.placeholder = 'Ask anything...';
-      el.suggestions = sampleSuggestions;
-    }
+    if (!el) return;
+    el.placeholder = 'Ask anything...';
+    el.suggestions = sampleSuggestions;
+    if (props?.search) el.setAttribute('search', '');
+    if (props?.voice) el.setAttribute('voice', '');
+    if (props?.attachments) el.attachments = props.attachments;
+    el.addEventListener('search', () => console.log('search clicked'));
+    el.addEventListener('voice', () => console.log('voice clicked'));
   });
   return (
     <kitn-prompt-input
-      ref={(e) => (el = e as HTMLElement)}
+      ref={(e) => (el = e as PromptInputEl)}
       style={{ display: 'block', width: '100%', padding: '16px' }}
     />
   );
@@ -97,7 +115,7 @@ const meta = {
         component: [
           '`<kitn-prompt-input>` is the framework-agnostic **web component** version of the chat composer — an auto-resizing textarea with a send button and optional suggestion chips, isolated in **Shadow DOM** so the host page\'s CSS can\'t leak in and the kit\'s styles can\'t leak out. SolidJS is bundled in, so the host needs nothing.',
           '**When to use:** adding a message composer to a non-Solid app (React, Vue, Svelte, plain HTML), or anywhere you want zero style conflicts. If you *are* in SolidJS and want fine-grained control, compose the `PromptInput` primitives instead.',
-          '**How to use:** register once with `import \'@kitnai/chat/elements\'`, configure it with JS **properties** (`placeholder`, `value`, `disabled`, `loading`, `suggestions`), and listen for **CustomEvents** (`submit`, `valuechange`, `suggestionclick`) directly on the element. Leave `value` unset to let the element manage its own input state.',
+          '**How to use:** register once with `import \'@kitnai/chat/elements\'`, configure it with JS **properties** (`placeholder`, `value`, `disabled`, `loading`, `suggestions`, `attachments`) and flag attributes (`search`, `voice` to show the Globe/Mic toolbar buttons), and listen for **CustomEvents** (`submit`, `valuechange`, `suggestionclick`, `search`, `voice`) directly on the element. Leave `value` unset to let the element manage its own input state; seed `attachments` to pre-populate staged files.',
           '**Placement:** pinned to the bottom of a chat surface, full width. Set `loading` while a response streams to show the busy state, and `disabled` to block input entirely.',
           'See the **Code** tab below for the HTML usage; the *SolidJS* story shows the same element inside a Solid component.',
         ].join('\n\n'),
@@ -121,3 +139,43 @@ export const InSolidJS: Story = {
   render: () => <PromptInputElement />,
   parameters: { docs: { source: { code: SOLID_SNIPPET, language: 'tsx' } } },
 };
+
+const TOOLBAR_SNIPPET = `<!-- show the Search (Globe) + Voice (Mic) toolbar buttons -->
+<kitn-prompt-input id="input" search voice></kitn-prompt-input>
+
+<script type="module">
+  import '@kitnai/chat/elements';
+  const input = document.getElementById('input');
+  input.addEventListener('search', () => console.log('search clicked'));
+  input.addEventListener('voice', () => console.log('voice clicked'));
+</script>`;
+
+/** With the **microphone** (and search) toolbar buttons enabled via the `voice`
+ *  and `search` flags. Clicking them fires `voice` / `search` CustomEvents. */
+export const WithVoiceAndSearch: Story = {
+  name: 'With Voice & Search',
+  render: () => <PromptInputElement search voice />,
+  parameters: { docs: { source: { code: TOOLBAR_SNIPPET, language: 'html' } } },
+};
+
+const ATTACHMENTS_SNIPPET = `<!-- seed staged attachments without an upload -->
+<kitn-prompt-input id="input" voice></kitn-prompt-input>
+
+<script type="module">
+  import '@kitnai/chat/elements';
+  const input = document.getElementById('input');
+  input.attachments = [
+    { id: 'a1', type: 'file', filename: 'architecture.png',
+      mediaType: 'image/png', url: 'data:image/svg+xml;utf8,...' },
+    { id: 'a2', type: 'file', filename: 'spec.pdf', mediaType: 'application/pdf' },
+  ];
+</script>`;
+
+/** Pre-populated with a couple of **attachments** (an image + a file) via the
+ *  `attachments` property, with the mic shown too. The paperclip still adds
+ *  more, and each chip can be removed. */
+export const WithAttachments: Story = {
+  name: 'With Attachments',
+  render: () => <PromptInputElement voice attachments={sampleAttachments} />,
+  parameters: { docs: { source: { code: ATTACHMENTS_SNIPPET, language: 'html' } } },
+};

package/src/elements/kitn-prompt-suggestions.stories.tsx

@@ -0,0 +1,157 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount } from 'solid-js';
+import './register'; // side effect: registers the custom elements
+
+type Item = string | { label: string; value?: string };
+
+// The web components are custom DOM elements, so declare the tags for JSX.
+declare module 'solid-js' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace JSX {
+    interface IntrinsicElements {
+      'kitn-prompt-suggestions': JSX.HTMLAttributes<HTMLElement> & {
+        variant?: string;
+        size?: string;
+        block?: boolean | string;
+        highlight?: string;
+      };
+    }
+  }
+}
+
+const suggestions: Item[] = [
+  'Explain the architecture',
+  'Show me a code example',
+  "What's deferred?",
+];
+
+/** Render `<kitn-prompt-suggestions>` with `suggestions` set as a property. */
+function SuggestionsElement(props: { suggestions: Item[]; variant?: string; size?: string; block?: boolean; highlight?: string }) {
+  let el: (HTMLElement & { suggestions?: Item[] }) | undefined;
+  onMount(() => {
+    if (!el) return;
+    el.suggestions = props.suggestions;
+    el.addEventListener('select', (e) => {
+      const ev = e as CustomEvent<{ value: string }>;
+      console.log('select', ev.detail.value);
+    });
+  });
+  return (
+    <kitn-prompt-suggestions
+      ref={(e) => (el = e as HTMLElement)}
+      variant={props.variant}
+      size={props.size}
+      block={props.block ? true : undefined}
+      highlight={props.highlight}
+      style={{ display: 'block', padding: '24px', 'max-width': '560px' }}
+    />
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-prompt-suggestions id="suggs" variant="outline"></kitn-prompt-suggestions>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  const suggs = document.getElementById('suggs');
+  suggs.suggestions = ['Explain the architecture', 'Show me a code example'];
+  suggs.addEventListener('select', (e) => console.log(e.detail.value));
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-prompt-suggestions',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-prompt-suggestions>` is the framework-agnostic **web component** for a row (or list) of clickable suggestion chips — starter prompts or follow-ups — isolated in **Shadow DOM**.',
+          '**When to use:** offering the user quick prompts to click instead of type, usually above an input. In SolidJS, use the `PromptSuggestion` primitive.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, set the `suggestions` **property** (strings, or `{ label, value }` when the displayed text differs from the emitted value), choose a `variant` and `size` (`sm` | `md` | `lg`; pills default to `lg`), optionally add the `block` flag for full-width rows or a `highlight` substring to emphasize, and listen for the `select` **CustomEvent**.",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** Default outline pills, wrapping in a row. */
+export const Default: Story = {
+  render: () => <SuggestionsElement suggestions={suggestions} variant="outline" />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** Ghost variant. */
+export const Ghost: Story = {
+  render: () => <SuggestionsElement suggestions={suggestions} variant="ghost" />,
+};
+
+/** Full-width left-aligned rows via the `block` flag. */
+export const Block: Story = {
+  render: () => <SuggestionsElement suggestions={suggestions} variant="outline" block />,
+};
+
+const searchSuggestions: Item[] = [
+  'How does SolidJS handle reactivity?',
+  'What makes SolidJS fast?',
+  'SolidJS vs Svelte comparison',
+];
+
+/** Filtered-search list: each row highlights the matched substring via the
+ *  `highlight` attribute (which forces the list-row layout). */
+export const WithHighlightedSearch: Story = {
+  name: 'With Highlighted Search',
+  render: () => (
+    <SuggestionsElement suggestions={searchSuggestions} highlight="Solid" />
+  ),
+  parameters: {
+    docs: {
+      source: {
+        code: `<kitn-prompt-suggestions id="suggs" highlight="Solid"></kitn-prompt-suggestions>
+
+<script type="module">
+  import '@kitnai/chat/elements';
+  const suggs = document.getElementById('suggs');
+  suggs.suggestions = [
+    'How does SolidJS handle reactivity?',
+    'What makes SolidJS fast?',
+    'SolidJS vs Svelte comparison',
+  ];
+</script>`,
+        language: 'html',
+      },
+    },
+  },
+};
+
+/** Sizes side by side — the default pill (`lg`) vs the smaller `sm` pill. */
+export const Sizes: Story = {
+  render: () => (
+    <div style={{ display: 'flex', 'flex-direction': 'column', gap: '8px', padding: '24px' }}>
+      <div>
+        <div style={{ 'font-size': '12px', opacity: '0.6', margin: '0 0 4px' }}>Default (lg)</div>
+        <SuggestionsElement suggestions={suggestions} variant="outline" />
+      </div>
+      <div>
+        <div style={{ 'font-size': '12px', opacity: '0.6', margin: '0 0 4px' }}>Small (sm)</div>
+        <SuggestionsElement suggestions={suggestions} variant="outline" size="sm" />
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      source: {
+        code: `<!-- default pill -->
+<kitn-prompt-suggestions variant="outline"></kitn-prompt-suggestions>
+<!-- smaller pill -->
+<kitn-prompt-suggestions variant="outline" size="sm"></kitn-prompt-suggestions>`,
+        language: 'html',
+      },
+    },
+  },
+};

package/src/elements/kitn-reasoning.stories.tsx

@@ -0,0 +1,76 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount } from 'solid-js';
+import './register'; // side effect: registers the custom elements
+
+// The web components are custom DOM elements, so declare the tags for JSX.
+declare module 'solid-js' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace JSX {
+    interface IntrinsicElements {
+      'kitn-reasoning': JSX.HTMLAttributes<HTMLElement>;
+    }
+  }
+}
+
+const sampleText =
+  'First I parse the request, then I plan the steps, then I execute and verify each one before responding.';
+
+/** Render the actual `<kitn-reasoning>` custom element with a `text` property. */
+function ReasoningElement(props: { text: string; streaming?: boolean }) {
+  let el: (HTMLElement & { text?: string; streaming?: boolean }) | undefined;
+  onMount(() => {
+    if (el) {
+      el.text = props.text;
+      if (props.streaming) el.streaming = true;
+    }
+  });
+  return (
+    <kitn-reasoning ref={(e) => (el = e as HTMLElement)} style={{ display: 'block', padding: '16px', 'max-width': '720px' }} />
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-reasoning id="reason" label="Reasoning"></kitn-reasoning>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  const reason = document.getElementById('reason');
+  reason.text = 'First I parse the request, then I plan the steps, then I execute.';
+  // reason.streaming = true;  // auto-expands while a thought streams in
+
+  // events are CustomEvents on the element (they do not bubble)
+  reason.addEventListener('openchange', (e) => console.log('open:', e.detail.open));
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-reasoning',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-reasoning>` is the framework-agnostic **web component** for a collapsible reasoning/thinking block that auto-expands while a thought is `streaming`, isolated in **Shadow DOM**.',
+          '**When to use:** surfacing model chain-of-thought in a non-Solid app. In SolidJS, compose the `Reasoning` primitives directly.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, set the body via the `text` **property**, set the `streaming` flag while it streams in, optionally drive the controlled `open` property, and listen for the `openchange` **CustomEvent**.",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** A collapsed reasoning block (the trigger toggles it). */
+export const Default: Story = {
+  render: () => <ReasoningElement text={sampleText} />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** With `streaming` set, the block auto-expands. */
+export const Streaming: Story = {
+  render: () => <ReasoningElement text={sampleText} streaming />,
+};

package/src/elements/kitn-response-stream.stories.tsx

@@ -0,0 +1,79 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount } from 'solid-js';
+import './register'; // side effect: registers the custom elements
+
+// The web components are custom DOM elements, so declare the tags for JSX.
+declare module 'solid-js' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace JSX {
+    interface IntrinsicElements {
+      'kitn-response-stream': JSX.HTMLAttributes<HTMLElement> & {
+        mode?: string;
+        speed?: number;
+      };
+    }
+  }
+}
+
+const STREAM_TEXT =
+  "This text reveals with a typewriter animation, streamed character by character — exactly how you'd render a live assistant reply.";
+
+/** Render `<kitn-response-stream>` with the `text` set as a JS property. */
+function StreamElement(props: { text: string; mode?: string; speed?: number }) {
+  let el: (HTMLElement & { text?: string }) | undefined;
+  onMount(() => {
+    if (el) el.text = props.text;
+  });
+  return (
+    <kitn-response-stream
+      ref={(e) => (el = e as HTMLElement)}
+      mode={props.mode}
+      speed={props.speed}
+      style={{ display: 'block', padding: '24px', 'max-width': '640px', 'line-height': 1.6 }}
+    />
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-response-stream id="stream" mode="typewriter" speed="20"></kitn-response-stream>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  const stream = document.getElementById('stream');
+  // text can be a string, or an AsyncIterable<string> for live streaming
+  stream.text = "Hello, this reveals one character at a time…";
+  stream.addEventListener('complete', () => console.log('done'));
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-response-stream',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-response-stream>` is the framework-agnostic **web component** that reveals text with a typewriter or fade animation — the building block for streamed assistant replies, isolated in **Shadow DOM**.',
+          '**When to use:** animating a response as it arrives. Pass a finished string to replay an animation, or an `AsyncIterable<string>` to drive it from a live stream. In SolidJS, use the `ResponseStream` primitive.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, set the `text` **property** (string or async iterable), tune `mode` (`typewriter` / `fade`) and `speed`, and listen for the `complete` **CustomEvent**.",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** Typewriter reveal (the default). */
+export const Typewriter: Story = {
+  render: () => <StreamElement text={STREAM_TEXT} mode="typewriter" speed={20} />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** Fade-in reveal, segment by segment. */
+export const Fade: Story = {
+  render: () => <StreamElement text={STREAM_TEXT} mode="fade" speed={10} />,
+};

package/src/elements/kitn-source-list.stories.tsx

@@ -0,0 +1,77 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount } from 'solid-js';
+import './register'; // side effect: registers the custom elements
+
+// The web components are custom DOM elements, so declare the tags for JSX.
+declare module 'solid-js' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace JSX {
+    interface IntrinsicElements {
+      'kitn-source-list': JSX.HTMLAttributes<HTMLElement>;
+    }
+  }
+}
+
+interface SourceItem {
+  href: string;
+  title?: string;
+  description?: string;
+  label?: string;
+  showFavicon?: boolean;
+}
+
+const sampleSources: SourceItem[] = [
+  { href: 'https://kitn.dev', title: 'kitn — the kit', description: 'Composable SolidJS + web-component chat UI.', showFavicon: true },
+  { href: 'https://solidjs.com', title: 'SolidJS', description: 'A reactive UI library.', showFavicon: true },
+];
+
+/** Render the actual `<kitn-source-list>` custom element with a `sources` property. */
+function SourceListElement() {
+  let el: (HTMLElement & { sources?: SourceItem[] }) | undefined;
+  onMount(() => {
+    if (el) el.sources = sampleSources;
+  });
+  return (
+    <kitn-source-list ref={(e) => (el = e as HTMLElement)} style={{ display: 'block', padding: '16px', 'max-width': '720px' }} />
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-source-list id="srcs" show-favicon></kitn-source-list>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  const srcs = document.getElementById('srcs');
+  srcs.sources = [
+    { href: 'https://kitn.dev', title: 'kitn — the kit', description: 'Composable chat UI.' },
+    { href: 'https://solidjs.com', title: 'SolidJS', description: 'A reactive UI library.' },
+  ];
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-source-list',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-source-list>` is the framework-agnostic **web component** for a wrapped row of citation links (each with its own hover-card preview), isolated in **Shadow DOM**.',
+          '**When to use:** showing the sources behind an assistant answer in a non-Solid app. For a single citation, use `<kitn-source>`; in SolidJS, compose `SourceList` + `Source`.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, set the data via the `sources` **property** (each item: `href`, `title`, `description`, `label`, `showFavicon`), and set `show-favicon` to enable favicons for all items (a per-item `showFavicon` overrides it).",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** Two citations rendered as a wrapped list with favicons. */
+export const Default: Story = {
+  render: () => <SourceListElement />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};

package/src/elements/kitn-source.stories.tsx

@@ -0,0 +1,87 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount } from 'solid-js';
+import './register'; // side effect: registers the custom elements
+
+// The web components are custom DOM elements, so declare the tags for JSX.
+declare module 'solid-js' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace JSX {
+    interface IntrinsicElements {
+      'kitn-source': JSX.HTMLAttributes<HTMLElement>;
+    }
+  }
+}
+
+/** Render the actual `<kitn-source>` custom element configured by attributes. */
+function SourceElement(props: {
+  href: string;
+  label?: string;
+  headline?: string;
+  description?: string;
+  showFavicon?: boolean;
+}) {
+  let el: HTMLElement | undefined;
+  onMount(() => {
+    if (!el) return;
+    el.setAttribute('href', props.href);
+    if (props.label) el.setAttribute('label', props.label);
+    if (props.headline) el.setAttribute('headline', props.headline);
+    if (props.description) el.setAttribute('description', props.description);
+    if (props.showFavicon) el.setAttribute('show-favicon', '');
+  });
+  return <kitn-source ref={(e) => (el = e as HTMLElement)} style={{ display: 'inline-block', padding: '16px' }} />;
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-source
+  href="https://kitn.dev"
+  label="kitn"
+  headline="kitn — the kit"
+  description="Composable SolidJS + web-component chat UI."
+  show-favicon
+></kitn-source>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-source',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-source>` is the framework-agnostic **web component** for a single citation link with a hover-card preview, isolated in **Shadow DOM**.',
+          '**When to use:** inlining a single source citation in a non-Solid app. For multiple sources, use `<kitn-source-list>`; in SolidJS, compose the `Source` primitives.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, then set `href` (the link, also the default label/favicon source), `label`, `headline` (the hover headline — note `headline`, not `title`), `description`, and the `show-favicon` flag via attributes.",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** A citation with a custom label, hover headline/description, and favicon. */
+export const Default: Story = {
+  render: () => (
+    <SourceElement
+      href="https://kitn.dev"
+      label="kitn"
+      headline="kitn — the kit"
+      description="Composable SolidJS + web-component chat UI."
+      showFavicon
+    />
+  ),
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** With no `label`, the trigger falls back to the domain. */
+export const DomainLabel: Story = {
+  name: 'Domain Label',
+  render: () => <SourceElement href="https://solidjs.com" description="A reactive UI library." />,
+};