@kitnai/chat 0.3.1 → 0.5.0

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

@@ -0,0 +1,75 @@
+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-markdown': JSX.HTMLAttributes<HTMLElement>;
+    }
+  }
+}
+
+const sampleMarkdown = `### Markdown
+Renders **bold**, _italic_, \`code\`, and lists:
+- one
+- two
+
+> and blockquotes.
+
+\`\`\`ts
+export function add(a: number, b: number): number {
+  return a + b;
+}
+\`\`\``;
+
+/** Render the actual `<kitn-markdown>` custom element with a `content` property. */
+function MarkdownElement(props: { content: string }) {
+  let el: (HTMLElement & { content?: string }) | undefined;
+  onMount(() => {
+    if (el) el.content = props.content;
+  });
+  return (
+    <kitn-markdown 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-markdown id="md" code-theme="github-dark-dimmed"></kitn-markdown>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  const md = document.getElementById('md');
+  md.content = '### Hello\\nRenders **bold**, _italic_, and \\\`code\\\`.';
+  // md.setAttribute('code-highlight', 'false'); // skip Shiki entirely
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-markdown',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-markdown>` is the framework-agnostic **web component** that renders a markdown string (with fenced-code syntax highlighting via Shiki) as a standalone element, isolated in **Shadow DOM**.',
+          '**When to use:** showing model output or any markdown in a non-Solid app without pulling in a markdown stack. In SolidJS, use the `Markdown` primitive directly.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, set the source via the `content` **property** (`el.content = '...'`), and tune rendering with the `prose-size`, `code-theme`, and `code-highlight` attributes.",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** Headings, emphasis, lists, a blockquote, and a highlighted code fence. */
+export const Default: Story = {
+  render: () => <MarkdownElement content={sampleMarkdown} />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};

package/src/elements/kitn-message-skills.stories.tsx

@@ -0,0 +1,74 @@
+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-message-skills': JSX.HTMLAttributes<HTMLElement>;
+    }
+  }
+}
+
+interface Skill {
+  id: string;
+  name: string;
+}
+
+const sampleSkills: Skill[] = [
+  { id: 's1', name: 'web-search' },
+  { id: 's2', name: 'code' },
+];
+
+/** Render the actual `<kitn-message-skills>` custom element with a `skills` property. */
+function MessageSkillsElement(props: { skills: Skill[] }) {
+  let el: (HTMLElement & { skills?: Skill[] }) | undefined;
+  onMount(() => {
+    if (el) el.skills = props.skills;
+  });
+  return (
+    <kitn-message-skills ref={(e) => (el = e as HTMLElement)} style={{ display: 'block', padding: '16px' }} />
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-message-skills id="skills"></kitn-message-skills>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  const skills = document.getElementById('skills');
+  skills.skills = [
+    { id: 's1', name: 'web-search' },
+    { id: 's2', name: 'code' },
+  ];
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-message-skills',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-message-skills>` is the framework-agnostic **web component** that badges which skills were active for a message, isolated in **Shadow DOM**.',
+          '**When to use:** annotating a message row with the skills/tools it used, in a non-Solid app. In SolidJS, use the `MessageSkills` primitive directly.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, then set the `skills` **property** to an array of `{ id, name }`.",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** Two active-skill badges. */
+export const Default: Story = {
+  render: () => <MessageSkillsElement skills={sampleSkills} />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};

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

@@ -0,0 +1,105 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount } from 'solid-js';
+import './register'; // side effect: registers the custom elements
+import type { ChatMessage } from './chat-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-message': JSX.HTMLAttributes<HTMLElement>;
+    }
+  }
+}
+
+const assistantMessage: ChatMessage = {
+  id: 'm-a',
+  role: 'assistant',
+  content:
+    "Here's the plan, with a quick code sample:\n\n```js\nconst kit = useKitn();\n```\n\nThat wires the kit into your component.",
+  reasoning: { text: 'The user wants X, so I should do Y then Z.', label: 'Reasoning' },
+  tools: [{ type: 'search', state: 'output-available', input: { query: 'kitn docs' }, output: { hits: 3 } }],
+  attachments: [
+    {
+      id: '1',
+      type: 'file',
+      filename: 'architecture.png',
+      mediaType: 'image/png',
+      url:
+        'data:image/svg+xml;utf8,' +
+        encodeURIComponent(
+          '<svg xmlns="http://www.w3.org/2000/svg" width="96" height="96"><rect width="96" height="96" rx="12" fill="#7c3aed"/><text x="48" y="60" font-size="42" text-anchor="middle" fill="white">◆</text></svg>',
+        ),
+    },
+  ],
+  actions: ['copy', 'like', 'dislike', 'regenerate'],
+};
+
+const userMessage: ChatMessage = {
+  id: 'm-u',
+  role: 'user',
+  content: 'How do I compose these myself?',
+};
+
+/** Render the actual `<kitn-message>` custom element with a `message` property. */
+function MessageElement(props: { message: ChatMessage }) {
+  let el: (HTMLElement & { message?: ChatMessage }) | undefined;
+  onMount(() => {
+    if (el) el.message = props.message;
+  });
+  return (
+    <kitn-message 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-message id="msg" style="display:block;"></kitn-message>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  const msg = document.getElementById('msg');
+  msg.message = {
+    id: 'm-a', role: 'assistant',
+    content: "Here's the plan:\\n\\n\\\`\\\`\\\`js\\nconst kit = useKitn();\\n\\\`\\\`\\\`",
+    reasoning: { text: 'The user wants X, so I should do Y.' },
+    tools: [{ type: 'search', state: 'output-available', output: { hits: 3 } }],
+    actions: ['copy', 'like', 'dislike', 'regenerate'],
+  };
+
+  // events are CustomEvents on the element (they do not bubble)
+  msg.addEventListener('messageaction', (e) => console.log(e.detail.action, e.detail.messageId));
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-message',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-message>` is the framework-agnostic **web component** for a single message row — markdown/plain content, an optional reasoning block, tool calls, attachments, and action buttons — all rendered from one `message` object (the same shape `<kitn-chat>` uses per message). It is the keystone of the "compose your own message list" pattern, isolated in **Shadow DOM**.',
+          "**When to use:** building a custom message thread in a non-Solid app, or anywhere you want to lay out the list yourself but keep the kit's rich message rendering. In SolidJS, compose the `Message` primitives for finer control.",
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, set the whole row via the `message` **property** (`el.message = {...}`), and listen for the `messageaction` **CustomEvent** for action-button clicks. For simple cases, set `role` + `content` attributes instead of a full object.",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** A rich assistant message: markdown, reasoning, a tool call, an attachment, and actions. */
+export const Assistant: Story = {
+  render: () => <MessageElement message={assistantMessage} />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** A plain user message (markdown defaults off for the user role). */
+export const User: Story = {
+  render: () => <MessageElement message={userMessage} />,
+};

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',
+      },
+    },
+  },
+};