@kitn.ai/ui 0.14.1

package/src/elements/prompt-input.tsx

@@ -0,0 +1,185 @@
+import { createEffect, createSignal, onMount, onCleanup } from 'solid-js';
+import { defineWebComponent } from './define';
+import { DefaultPromptInput } from './default-input';
+import type { AttachmentData } from '../components/attachments';
+import type { SlashCommandItem } from '../components/slash-command';
+import type { CustomAction } from './chat-types';
+
+/** Parse a single light-DOM `<kai-slash-command>` element into a SlashCommandItem.
+ *  Attribute mapping:
+ *   - `command`     → SlashCommandItem.id       (required; empty string fallback)
+ *   - textContent   → SlashCommandItem.label    (primary); `label` attr as fallback
+ *   - `description` → SlashCommandItem.description
+ *   - `category`    → SlashCommandItem.category
+ */
+export function parseKaiSlashCommandElement(n: Element): SlashCommandItem {
+  return {
+    id: n.getAttribute('command') ?? '',
+    label: n.textContent?.trim() || n.getAttribute('label') || n.getAttribute('command') || '',
+    description: n.getAttribute('description') ?? undefined,
+    category: n.getAttribute('category') ?? undefined,
+  };
+}
+
+interface Props extends Record<string, unknown> {
+  /** Controlled value of the input. When set, the host owns the text and must
+   *  update it on `kai-value-change`; leave unset for uncontrolled behavior. */
+  value?: string;
+  /** Placeholder text shown in the empty input. */
+  placeholder?: string;
+  /** Disable the input and submit button entirely (non-interactive). */
+  disabled?: boolean;
+  /** Show the loading/streaming state and block submit (use while awaiting a
+   *  reply). */
+  loading?: boolean;
+  /** Starter prompts shown above the input. Clicking one follows
+   *  `suggestionMode`. Set as a JS property. */
+  suggestions?: string[];
+  /** What clicking a suggestion does: `'submit'` (default) sends it immediately
+   *  as if typed and submitted; `'fill'` just places it in the input. */
+  suggestionMode?: 'submit' | 'fill';
+  /** Slash commands — when set, typing `/` opens the command palette. Set as a
+   *  JS property. */
+  slashCommands?: SlashCommandItem[];
+  /** Command ids to highlight as active. */
+  slashActiveIds?: string[];
+  /** Single-line palette rows. */
+  slashCompact?: boolean;
+  /** Show a Search (Globe) button in the left toolbar; clicking it fires a
+   *  `search` event. */
+  search?: boolean;
+  /** Show a Voice (Mic) button in the left toolbar; clicking it fires a `voice`
+   *  event. */
+  voice?: boolean;
+  /** When set and `loading` is true, the send button is replaced by a Stop
+   *  button (square icon, "Stop" aria-label). Clicking it fires `kai-stop`. */
+  stoppable?: boolean;
+  /** Attachments to seed the input with (so a consumer can pre-populate staged
+   *  files without an upload). Set as a JS property; the element then manages its
+   *  own attachment state from there (add via the paperclip, remove per chip). */
+  attachments?: AttachmentData[];
+}
+
+/** Events fired by `<kai-prompt-input>`. */
+interface Events {
+  /** The user submitted the prompt (Enter or send button) with its attachments. */
+  'kai-submit': { value: string; attachments: AttachmentData[] };
+  /** The input text changed (fires on every keystroke). */
+  'kai-value-change': { value: string };
+  /** A suggestion was clicked while `suggestion-mode="fill"`. */
+  'kai-suggestion-click': { value: string };
+  /** A slash command was chosen from the palette. */
+  'kai-slash-select': { command: SlashCommandItem };
+  /** The Search (Globe) toolbar button was clicked. */
+  'kai-search': Record<string, never>;
+  /** The Voice (Mic) toolbar button was clicked. */
+  'kai-voice': Record<string, never>;
+  /** The Stop button was clicked while `stoppable` and `loading` are both true. */
+  'kai-stop': Record<string, never>;
+  /** A custom `<kai-action>` toolbar button was clicked. `action` is the `id` of
+   *  the `<kai-action>` element that was clicked. */
+  'kai-toolbar-action': { action: string };
+}
+
+defineWebComponent<Props, Events>('kai-prompt-input', {
+  value: undefined,
+  placeholder: 'Send a message...',
+  disabled: false,
+  loading: false,
+  suggestions: undefined,
+  suggestionMode: 'submit',
+  slashCommands: undefined,
+  slashActiveIds: undefined,
+  slashCompact: false,
+  search: false,
+  voice: false,
+  stoppable: false,
+  attachments: undefined,
+}, (props, { dispatch, flag, element }) => {
+  const [internal, setInternal] = createSignal(props.value ?? '');
+  // Seed staged attachments from the `attachments` property; the element manages
+  // its own state from there (paperclip adds, per-chip remove deletes).
+  const [attachments, setAttachments] = createSignal<AttachmentData[]>(props.attachments ?? []);
+  // Re-seed when the `attachments` property is (re)assigned by the consumer
+  // (e.g. set via a `ref` after mount). Subsequent in-element edits stay local.
+  createEffect(() => {
+    if (props.attachments) setAttachments(props.attachments);
+  });
+
+  // Read declarative <kai-action> and <kai-slash-command> children from light DOM —
+  // same pattern as kai-message. Shadow DOM with no <slot> suppresses them visually;
+  // they are invisible data carriers. One MutationObserver covers both element types.
+  const [toolbarActions, setToolbarActions] = createSignal<CustomAction[]>([]);
+  const [slottedSlashCommands, setSlottedSlashCommands] = createSignal<SlashCommandItem[]>([]);
+  onMount(() => {
+    const readActions = () => {
+      const nodes = [...element.querySelectorAll('kai-action')];
+      setToolbarActions(nodes.map(n => ({
+        id: n.id || n.getAttribute('action') || '',
+        label: n.textContent?.trim() || n.getAttribute('label') || n.id || '',
+        icon: n.getAttribute('icon') ?? undefined,
+        tooltip: n.getAttribute('tooltip') ?? undefined,
+      })));
+    };
+    const readSlashCommands = () => {
+      const nodes = [...element.querySelectorAll('kai-slash-command')];
+      setSlottedSlashCommands(nodes.map(parseKaiSlashCommandElement));
+    };
+    const readAll = () => { readActions(); readSlashCommands(); };
+    readAll();
+    const observer = new MutationObserver(readAll);
+    observer.observe(element, { childList: true, attributes: true, subtree: true });
+    onCleanup(() => observer.disconnect());
+  });
+
+  const current = () => props.value ?? internal();
+
+  const handleChange = (v: string) => { setInternal(v); dispatch('kai-value-change', { value: v }); };
+  const handleSubmit = () => {
+    dispatch('kai-submit', { value: current(), attachments: attachments() });
+    setAttachments([]);
+  };
+  const handleSuggestionClick = (v: string) => {
+    if ((props.suggestionMode ?? 'submit') === 'fill') {
+      handleChange(v);
+      dispatch('kai-suggestion-click', { value: v });
+    } else {
+      // Default: behave as if the user typed the suggestion and pressed submit.
+      dispatch('kai-submit', { value: v, attachments: attachments() });
+      setAttachments([]);
+    }
+  };
+
+  // Prop slash commands take precedence; slotted children are appended after.
+  const allSlashCommands = () => [
+    ...(props.slashCommands ?? []),
+    ...slottedSlashCommands(),
+  ];
+
+  return (
+    <DefaultPromptInput
+      value={current()}
+      placeholder={props.placeholder}
+      disabled={flag('disabled')}
+      loading={flag('loading')}
+      stoppable={flag('stoppable')}
+      suggestions={props.suggestions}
+      attachments={attachments()}
+      slashCommands={allSlashCommands().length ? allSlashCommands() : undefined}
+      slashActiveIds={props.slashActiveIds}
+      slashCompact={flag('slashCompact')}
+      search={flag('search')}
+      voice={flag('voice')}
+      toolbarActions={toolbarActions()}
+      onValueChange={handleChange}
+      onSubmit={handleSubmit}
+      onSuggestionClick={handleSuggestionClick}
+      onAttachmentsChange={setAttachments}
+      onSearch={() => dispatch('kai-search')}
+      onVoice={() => dispatch('kai-voice')}
+      onStop={() => dispatch('kai-stop')}
+      onSlashSelect={(command) => dispatch('kai-slash-select', { command })}
+      onAction={(id) => dispatch('kai-toolbar-action', { action: id })}
+    />
+  );
+});

package/src/elements/prompt-suggestions.declarative.test.tsx

@@ -0,0 +1,164 @@
+/**
+ * Unit tests for the declarative `<kai-suggestion>` light-DOM API of
+ * `<kai-suggestions>`.
+ *
+ * Strategy: the `defineWebComponent` call registers a real Shadow-DOM custom
+ * element which requires a full browser environment (Constructable Stylesheets,
+ * shadow roots, etc.) and is therefore not suitable for jsdom unit tests.
+ * Instead we:
+ *   1. Test the exported `parseSuggestionNode` helper in isolation — it has no
+ *      DOM dependencies beyond `Element`, which jsdom provides perfectly.
+ *   2. Test that the merged list of prop + slotted items renders chip buttons
+ *      and fires click handlers correctly via `PromptSuggestion` directly,
+ *      mirroring the pattern used in `message-action-bar.test.tsx`.
+ */
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import '@testing-library/jest-dom/vitest';
+import { render, cleanup, fireEvent } from '@solidjs/testing-library';
+import { For } from 'solid-js';
+import { parseSuggestionNode } from './prompt-suggestions';
+import { PromptSuggestion } from '../components/prompt-suggestion';
+
+afterEach(cleanup);
+
+// ---------------------------------------------------------------------------
+// parseSuggestionNode — pure helper
+// ---------------------------------------------------------------------------
+
+describe('parseSuggestionNode', () => {
+  function makeNode(textContent: string, value?: string): Element {
+    const el = document.createElement('kai-suggestion');
+    el.textContent = textContent;
+    if (value !== undefined) el.setAttribute('value', value);
+    return el;
+  }
+
+  it('uses textContent as label', () => {
+    const item = parseSuggestionNode(makeNode('Use Vue'));
+    expect(item).toMatchObject({ label: 'Use Vue' });
+  });
+
+  it('uses value attribute as value when present', () => {
+    const item = parseSuggestionNode(makeNode('Use Vue', 'vue'));
+    expect(item).toMatchObject({ label: 'Use Vue', value: 'vue' });
+  });
+
+  it('falls back to textContent as value when value attribute is absent', () => {
+    const item = parseSuggestionNode(makeNode('Use Vue'));
+    expect(item).toMatchObject({ label: 'Use Vue', value: 'Use Vue' });
+  });
+
+  it('trims leading/trailing whitespace from textContent', () => {
+    const item = parseSuggestionNode(makeNode('  Explain the architecture  '));
+    expect(item).toMatchObject({ label: 'Explain the architecture' });
+  });
+
+  it('handles empty textContent with a value attribute', () => {
+    const item = parseSuggestionNode(makeNode('', 'vue'));
+    expect(item).toMatchObject({ label: '', value: 'vue' });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Merge + render: prop suggestions + slotted suggestions combine correctly
+// ---------------------------------------------------------------------------
+
+type Item = string | { label: string; value?: string };
+
+const labelOf = (s: Item) => (typeof s === 'string' ? s : s.label);
+const valueOf = (s: Item) => (typeof s === 'string' ? s : s.value ?? s.label);
+
+/**
+ * Minimal test harness that renders a list of `Item`s as `PromptSuggestion`
+ * chips and records which value was clicked — mirrors the render path in
+ * `prompt-suggestions.tsx`.
+ */
+function SuggestionList(props: { items: Item[]; onSelect: (value: string) => void }) {
+  return (
+    <div>
+      <For each={props.items}>
+        {(s) => (
+          <PromptSuggestion onClick={() => props.onSelect(valueOf(s))}>
+            {labelOf(s)}
+          </PromptSuggestion>
+        )}
+      </For>
+    </div>
+  );
+}
+
+describe('suggestion chip rendering and click events', () => {
+  it('renders one chip per item', () => {
+    const { getByText } = render(() => (
+      <SuggestionList
+        items={['Explain the architecture', 'Show me a code example']}
+        onSelect={() => {}}
+      />
+    ));
+    expect(getByText('Explain the architecture')).toBeInTheDocument();
+    expect(getByText('Show me a code example')).toBeInTheDocument();
+  });
+
+  it('fires onSelect with the string value when a string item is clicked', () => {
+    const onSelect = vi.fn();
+    const { getByText } = render(() => (
+      <SuggestionList items={['Use Vue']} onSelect={onSelect} />
+    ));
+    fireEvent.click(getByText('Use Vue'));
+    expect(onSelect).toHaveBeenCalledWith('Use Vue');
+  });
+
+  it('fires onSelect with item.value for an object item with an explicit value', () => {
+    const onSelect = vi.fn();
+    const { getByText } = render(() => (
+      <SuggestionList
+        items={[{ label: 'Use Vue', value: 'vue' }]}
+        onSelect={onSelect}
+      />
+    ));
+    fireEvent.click(getByText('Use Vue'));
+    expect(onSelect).toHaveBeenCalledWith('vue');
+  });
+
+  it('falls back to label as value for an object item without explicit value', () => {
+    const onSelect = vi.fn();
+    const { getByText } = render(() => (
+      <SuggestionList
+        items={[{ label: 'Use Vue' }]}
+        onSelect={onSelect}
+      />
+    ));
+    fireEvent.click(getByText('Use Vue'));
+    expect(onSelect).toHaveBeenCalledWith('Use Vue');
+  });
+
+  it('renders prop items before declarative (slotted) items', () => {
+    // Simulate the merge: prop first, slotted second.
+    const propItems: Item[] = [{ label: 'Prop item', value: 'prop' }];
+    const slottedItems: Item[] = [{ label: 'Slotted item', value: 'slotted' }];
+    const merged = [...propItems, ...slottedItems];
+
+    const { getAllByRole } = render(() => (
+      <SuggestionList items={merged} onSelect={() => {}} />
+    ));
+    const buttons = getAllByRole('button');
+    expect(buttons).toHaveLength(2);
+    expect(buttons[0]).toHaveTextContent('Prop item');
+    expect(buttons[1]).toHaveTextContent('Slotted item');
+  });
+
+  it('parseSuggestionNode produces items that render and fire the correct value', () => {
+    // End-to-end: parse a DOM node → render it → click → verify event value.
+    const onSelect = vi.fn();
+    const el = document.createElement('kai-suggestion');
+    el.textContent = 'Use Vue';
+    el.setAttribute('value', 'vue');
+
+    const parsed = parseSuggestionNode(el);
+    const { getByText } = render(() => (
+      <SuggestionList items={[parsed]} onSelect={onSelect} />
+    ));
+    fireEvent.click(getByText('Use Vue'));
+    expect(onSelect).toHaveBeenCalledWith('vue');
+  });
+});

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

@@ -0,0 +1,213 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount } from 'solid-js';
+import './register'; // side effect: registers the custom elements
+import { argTypesFor, specDescription } from '../stories/docs/element-controls';
+
+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 {
+      'kai-suggestions': JSX.HTMLAttributes<HTMLElement> & {
+        variant?: string;
+        size?: string;
+        block?: boolean | string;
+        highlight?: string;
+      };
+      /** Light-DOM data carrier for declarative suggestion chips inside `<kai-suggestions>`. */
+      'kai-suggestion': JSX.HTMLAttributes<HTMLElement> & {
+        value?: string;
+      };
+    }
+  }
+}
+
+const suggestions: Item[] = [
+  'Explain the architecture',
+  'Show me a code example',
+  "What's deferred?",
+];
+
+/** Render `<kai-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('kai-select', (e) => {
+      const ev = e as CustomEvent<{ value: string }>;
+      console.log('kai-select', ev.detail.value);
+    });
+  });
+  return (
+    <kai-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 -->
+<kai-suggestions id="suggs" variant="outline"></kai-suggestions>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';   // registers the custom elements
+
+  const suggs = document.getElementById('suggs');
+  suggs.suggestions = ['Explain the architecture', 'Show me a code example'];
+  suggs.addEventListener('kai-select', (e) => console.log(e.detail.value));
+</script>`;
+
+const meta = {
+  title: 'Components/Suggestions',
+  tags: ['autodocs'],
+  argTypes: argTypesFor('kai-suggestions'),
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: specDescription('kai-suggestions', [
+          '`<kai-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.',
+          '**Placement:** above the prompt input in the empty/welcome state, or below the last assistant message as follow-up chips; it is a `block` element and takes the full width of its container.',
+          "**How to use:** register once with `import '@kitn.ai/ui/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 `kai-select` **CustomEvent**.",
+          'See the **Code** tab for HTML usage.',
+        ]),
+    },
+  },
+} 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: `<kai-suggestions id="suggs" highlight="Solid"></kai-suggestions>
+
+<script type="module">
+  import '@kitn.ai/ui/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 -->
+<kai-suggestions variant="outline"></kai-suggestions>
+<!-- smaller pill -->
+<kai-suggestions variant="outline" size="sm"></kai-suggestions>`,
+        language: 'html',
+      },
+    },
+  },
+};
+
+const DECLARATIVE_HTML_SNIPPET = `<!-- Works in any framework or plain HTML — no JS property assignment needed -->
+<kai-suggestions id="suggs" variant="outline">
+  <kai-suggestion value="explain">Explain the architecture</kai-suggestion>
+  <kai-suggestion value="example">Show me a code example</kai-suggestion>
+  <kai-suggestion value="deferred">What's deferred?</kai-suggestion>
+</kai-suggestions>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';   // registers the custom elements
+
+  document.getElementById('suggs').addEventListener('kai-select', (e) => {
+    console.log('kai-select', e.detail.value);
+  });
+</script>`;
+
+/**
+ * Declare each suggestion as a `<kai-suggestion>` child element — no `suggestions`
+ * property or JS array wiring needed. The `value` attribute sets the emitted
+ * value; `textContent` is the displayed label. Children are light-DOM data
+ * carriers hidden by the Shadow DOM — pure data, no visible output of their own.
+ * Mix with the `suggestions` prop: prop items render first, declarative children after.
+ */
+export const DeclarativeSuggestions: Story = {
+  name: 'Declarative Suggestions (kai-suggestion)',
+  render: () => {
+    let el: HTMLElement | undefined;
+    onMount(() => {
+      if (!el) return;
+      el.addEventListener('kai-select', (e) =>
+        console.log('kai-select', (e as CustomEvent<{ value: string }>).detail.value),
+      );
+    });
+    return (
+      <kai-suggestions
+        ref={(e) => (el = e as HTMLElement)}
+        variant="outline"
+        style={{ display: 'block', padding: '24px', 'max-width': '560px' }}
+      >
+        <kai-suggestion value="explain">Explain the architecture</kai-suggestion>
+        <kai-suggestion value="example">Show me a code example</kai-suggestion>
+        <kai-suggestion value="deferred">What's deferred?</kai-suggestion>
+      </kai-suggestions>
+    );
+  },
+  parameters: {
+    docs: {
+      source: { code: DECLARATIVE_HTML_SNIPPET, language: 'html' },
+    },
+  },
+};

package/src/elements/prompt-suggestions.tsx

@@ -0,0 +1,94 @@
+import { For, createSignal, onMount, onCleanup } from 'solid-js';
+import { defineWebComponent } from './define';
+import { PromptSuggestion } from '../components/prompt-suggestion';
+
+type Item = string | { label: string; value?: string };
+
+interface Props extends Record<string, unknown> {
+  /** The suggestions. Strings, or `{ label, value }` when the displayed text
+   *  and the emitted value differ. Set as a JS property. */
+  suggestions: Item[];
+  /** Chip style: `'outline'` (default), `'ghost'`, or `'default'` (filled). */
+  variant?: 'outline' | 'ghost' | 'default';
+  /** Size preset for each chip. Defaults to the pill default (`'lg'`); pass
+   *  `'sm'` for smaller pills (or `'md'`). */
+  size?: 'sm' | 'md' | 'lg' | 'icon' | 'icon-sm';
+  /** Full-width left-aligned rows instead of pills. */
+  block?: boolean;
+  /** Substring to highlight within each suggestion. */
+  highlight?: string;
+}
+
+/** Events fired by `<kai-suggestions>`. */
+interface Events {
+  /** A suggestion was clicked. */
+  'kai-select': { value: string };
+}
+
+const labelOf = (s: Item) => (typeof s === 'string' ? s : s.label);
+const valueOf = (s: Item) => (typeof s === 'string' ? s : s.value ?? s.label);
+
+/** Parse a single `<kai-suggestion>` node into an `Item` descriptor. */
+export function parseSuggestionNode(n: Element): Item {
+  const text = n.textContent?.trim() ?? '';
+  const value = n.getAttribute('value') ?? text;
+  return { label: text, value };
+}
+
+/**
+ * `<kai-suggestions>` — a row/list of suggestion chips. Data via the
+ * `suggestions` property; `variant`/`block`/`highlight` attributes; emits
+ * `select`.
+ *
+ * Alternatively, declare chips as `<kai-suggestion>` child elements
+ * (light-DOM data carriers — hidden by the Shadow DOM):
+ *
+ * ```html
+ * <kai-suggestions>
+ *   <kai-suggestion value="vue">Use Vue</kai-suggestion>
+ *   <kai-suggestion value="react">Use React</kai-suggestion>
+ * </kai-suggestions>
+ * ```
+ */
+defineWebComponent<Props, Events>('kai-suggestions', {
+  suggestions: [],
+  variant: 'outline',
+  size: undefined,
+  block: false,
+  highlight: undefined,
+}, (props, { dispatch, flag, element }) => {
+  // Read declarative <kai-suggestion> children from light DOM.
+  // Shadow DOM with no <slot> suppresses them visually — they're invisible data carriers.
+  const [slottedSuggestions, setSlottedSuggestions] = createSignal<Item[]>([]);
+  onMount(() => {
+    const read = () => {
+      const nodes = [...element.querySelectorAll('kai-suggestion')];
+      setSlottedSuggestions(nodes.map(parseSuggestionNode));
+    };
+    read();
+    const observer = new MutationObserver(read);
+    observer.observe(element, { childList: true, attributes: true, subtree: true });
+    onCleanup(() => observer.disconnect());
+  });
+
+  // Merge prop suggestions (first) with declarative children (after).
+  const allSuggestions = () => [...(props.suggestions ?? []), ...slottedSuggestions()];
+
+  return (
+    <div class={flag('block') ? 'flex flex-col gap-2' : 'flex flex-wrap gap-2'}>
+      <For each={allSuggestions()}>
+        {(s) => (
+          <PromptSuggestion
+            variant={props.variant}
+            size={props.size}
+            block={flag('block')}
+            highlight={props.highlight}
+            onClick={() => dispatch('kai-select', { value: valueOf(s) })}
+          >
+            {labelOf(s)}
+          </PromptSuggestion>
+        )}
+      </For>
+    </div>
+  );
+});