@kitn.ai/ui 0.14.1

package/src/elements/prompt-input-slash-command.test.tsx

@@ -0,0 +1,128 @@
+/**
+ * Unit tests for parseKaiSlashCommandElement and the merge behaviour
+ * in kai-prompt-input's declarative <kai-slash-command> reader.
+ *
+ * Strategy: test the exported pure helper directly with synthetic DOM elements
+ * (no Shadow DOM, no custom element upgrade needed).
+ * Merge behaviour is verified by constructing the same arrays the element would
+ * produce and asserting the result — pure array logic, no browser environment needed.
+ */
+import { describe, it, expect } from 'vitest';
+import { parseKaiSlashCommandElement } from './prompt-input';
+
+// ---------------------------------------------------------------------------
+// parseKaiSlashCommandElement — attribute → SlashCommandItem mapping
+// ---------------------------------------------------------------------------
+
+describe('parseKaiSlashCommandElement', () => {
+  function makeEl(
+    attrs: Record<string, string | null>,
+    textContent?: string,
+  ): Element {
+    const el = document.createElement('kai-slash-command');
+    for (const [k, v] of Object.entries(attrs)) {
+      if (v !== null) el.setAttribute(k, v);
+    }
+    if (textContent !== undefined) el.textContent = textContent;
+    return el;
+  }
+
+  it('maps command attr → id, textContent → label, description attr → description', () => {
+    const el = makeEl(
+      { command: 'summarize', description: 'Summarize the thread' },
+      'summarize',
+    );
+    expect(parseKaiSlashCommandElement(el)).toEqual({
+      id: 'summarize',
+      label: 'summarize',
+      description: 'Summarize the thread',
+      category: undefined,
+    });
+  });
+
+  it('maps category attr → category', () => {
+    const el = makeEl(
+      { command: 'search', category: 'tools' },
+      'search',
+    );
+    expect(parseKaiSlashCommandElement(el).category).toBe('tools');
+  });
+
+  it('falls back to label attr when textContent is empty', () => {
+    const el = makeEl({ command: 'help', label: 'Help' }, '');
+    expect(parseKaiSlashCommandElement(el).label).toBe('Help');
+  });
+
+  it('falls back to command attr as label when both textContent and label attr are absent', () => {
+    const el = makeEl({ command: 'debug' });
+    expect(parseKaiSlashCommandElement(el).label).toBe('debug');
+  });
+
+  it('returns empty string for id when command attr is absent', () => {
+    const el = makeEl({}, 'orphan');
+    expect(parseKaiSlashCommandElement(el).id).toBe('');
+  });
+
+  it('returns undefined for optional attrs when absent', () => {
+    const el = makeEl({ command: 'bare' }, 'bare');
+    const item = parseKaiSlashCommandElement(el);
+    expect(item.description).toBeUndefined();
+    expect(item.category).toBeUndefined();
+  });
+
+  it('whitespace-trims textContent for the label', () => {
+    const el = makeEl({ command: 'trim' }, '  trim  ');
+    expect(parseKaiSlashCommandElement(el).label).toBe('trim');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// merge behaviour — prop slashCommands + slotted children
+// ---------------------------------------------------------------------------
+
+describe('slashCommands merge (prop + declarative children)', () => {
+  function makeEl(command: string, label: string, description?: string): Element {
+    const el = document.createElement('kai-slash-command');
+    el.setAttribute('command', command);
+    el.textContent = label;
+    if (description) el.setAttribute('description', description);
+    return el;
+  }
+
+  it('prop items appear before slotted children in the merged list', () => {
+    const propItems = [{ id: 'prop-cmd', label: 'Prop Command' }];
+    const slottedItems = [
+      parseKaiSlashCommandElement(makeEl('child-cmd', 'Child Command')),
+    ];
+    const merged = [...propItems, ...slottedItems];
+    expect(merged[0].id).toBe('prop-cmd');
+    expect(merged[1].id).toBe('child-cmd');
+  });
+
+  it('merged list is empty when both prop and children are absent', () => {
+    const propItems: ReturnType<typeof parseKaiSlashCommandElement>[] = [];
+    const slottedItems: ReturnType<typeof parseKaiSlashCommandElement>[] = [];
+    expect([...propItems, ...slottedItems]).toHaveLength(0);
+  });
+
+  it('slotted-only: single child appears as the only item', () => {
+    const el = makeEl('summarize', 'Summarize', 'Summarize the thread');
+    const merged = [...[], parseKaiSlashCommandElement(el)];
+    expect(merged).toHaveLength(1);
+    expect(merged[0]).toEqual({
+      id: 'summarize',
+      label: 'Summarize',
+      description: 'Summarize the thread',
+      category: undefined,
+    });
+  });
+
+  it('prop-only: prop items flow through unchanged', () => {
+    const propItems = [
+      { id: 'a', label: 'Alpha', description: 'First' },
+      { id: 'b', label: 'Beta' },
+    ];
+    const merged = [...propItems, ...([] as typeof propItems)];
+    expect(merged).toEqual(propItems);
+  });
+});

package/src/elements/prompt-input-stoppable.test.tsx

@@ -0,0 +1,88 @@
+/**
+ * Unit tests for the stoppable Stop button affordance in DefaultPromptInput.
+ *
+ * Strategy: test DefaultPromptInput (the Solid component) directly — the
+ * defineWebComponent custom element requires a full browser environment
+ * (Constructable Stylesheets, shadow roots) unsuitable for jsdom.
+ * This mirrors the pattern in prompt-suggestions.declarative.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 { DefaultPromptInput } from './default-input';
+
+afterEach(cleanup);
+
+const noop = () => {};
+const baseProps = {
+  value: '',
+  onValueChange: noop,
+  onSubmit: noop,
+  onSuggestionClick: noop,
+};
+
+describe('DefaultPromptInput stoppable Stop button', () => {
+  it('renders the send button (not Stop) when loading=false stoppable=false', () => {
+    const { getByTestId, queryByTestId } = render(() => (
+      <DefaultPromptInput {...baseProps} loading={false} stoppable={false} />
+    ));
+    expect(getByTestId('send')).toBeInTheDocument();
+    expect(queryByTestId('stop')).not.toBeInTheDocument();
+  });
+
+  it('renders the send button (not Stop) when stoppable=true but loading=false', () => {
+    const { getByTestId, queryByTestId } = render(() => (
+      <DefaultPromptInput {...baseProps} loading={false} stoppable={true} />
+    ));
+    expect(getByTestId('send')).toBeInTheDocument();
+    expect(queryByTestId('stop')).not.toBeInTheDocument();
+  });
+
+  it('renders the send button (not Stop) when loading=true but stoppable=false', () => {
+    const { getByTestId, queryByTestId } = render(() => (
+      <DefaultPromptInput {...baseProps} loading={true} stoppable={false} />
+    ));
+    expect(getByTestId('send')).toBeInTheDocument();
+    expect(queryByTestId('stop')).not.toBeInTheDocument();
+  });
+
+  it('renders the Stop button (not send) when both loading=true and stoppable=true', () => {
+    const { getByTestId, queryByTestId } = render(() => (
+      <DefaultPromptInput {...baseProps} loading={true} stoppable={true} />
+    ));
+    expect(getByTestId('stop')).toBeInTheDocument();
+    expect(queryByTestId('send')).not.toBeInTheDocument();
+  });
+
+  it('Stop button has accessible label "Stop"', () => {
+    const { getByLabelText } = render(() => (
+      <DefaultPromptInput {...baseProps} loading={true} stoppable={true} />
+    ));
+    expect(getByLabelText('Stop')).toBeInTheDocument();
+  });
+
+  it('clicking the Stop button calls onStop', () => {
+    const onStop = vi.fn();
+    const { getByTestId } = render(() => (
+      <DefaultPromptInput {...baseProps} loading={true} stoppable={true} onStop={onStop} />
+    ));
+    fireEvent.click(getByTestId('stop'));
+    expect(onStop).toHaveBeenCalledOnce();
+  });
+
+  it('clicking the Stop button does NOT call onSubmit', () => {
+    const onSubmit = vi.fn();
+    const onStop = vi.fn();
+    const { getByTestId } = render(() => (
+      <DefaultPromptInput
+        {...baseProps}
+        onSubmit={onSubmit}
+        loading={true}
+        stoppable={true}
+        onStop={onStop}
+      />
+    ));
+    fireEvent.click(getByTestId('stop'));
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+});

package/src/elements/prompt-input-toolbar-actions.test.tsx

@@ -0,0 +1,120 @@
+/**
+ * Unit tests for custom `<kai-action>` toolbar buttons in DefaultPromptInput.
+ *
+ * Strategy: test DefaultPromptInput (the Solid component) directly — the
+ * defineWebComponent custom element requires a full browser environment
+ * (Constructable Stylesheets, shadow roots) unsuitable for jsdom.
+ * This mirrors the pattern in prompt-input-stoppable.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 { DefaultPromptInput } from './default-input';
+import type { CustomAction } from './chat-types';
+
+afterEach(cleanup);
+
+const noop = () => {};
+const baseProps = {
+  value: '',
+  onValueChange: noop,
+  onSubmit: noop,
+  onSuggestionClick: noop,
+};
+
+const ACTIONS: CustomAction[] = [
+  { id: 'attach', label: 'Attach', icon: 'paperclip', tooltip: 'Attach file' },
+  { id: 'bookmark', label: 'Bookmark', icon: 'bookmark', tooltip: 'Save for later' },
+];
+
+describe('DefaultPromptInput custom toolbar actions', () => {
+  it('renders no custom buttons when toolbarActions is empty', () => {
+    const { queryByRole } = render(() => (
+      <DefaultPromptInput {...baseProps} toolbarActions={[]} />
+    ));
+    // The send button is the only button when no custom actions are set.
+    // (paperclip attach is absent because onAttachmentsChange is not provided)
+    const buttons = queryByRole('button', { name: 'Attach' });
+    expect(buttons).not.toBeInTheDocument();
+  });
+
+  it('renders one ghost button per custom action', () => {
+    const { getAllByRole } = render(() => (
+      <DefaultPromptInput {...baseProps} toolbarActions={ACTIONS} />
+    ));
+    // aria-label is set to action.label on each button
+    const attachBtn = getAllByRole('button').find(
+      (b) => b.getAttribute('aria-label') === 'Attach',
+    );
+    const bookmarkBtn = getAllByRole('button').find(
+      (b) => b.getAttribute('aria-label') === 'Bookmark',
+    );
+    expect(attachBtn).toBeInTheDocument();
+    expect(bookmarkBtn).toBeInTheDocument();
+  });
+
+  it('sets data-action attribute to the action id', () => {
+    const { getAllByRole } = render(() => (
+      <DefaultPromptInput {...baseProps} toolbarActions={ACTIONS} />
+    ));
+    const attachBtn = getAllByRole('button').find(
+      (b) => b.getAttribute('aria-label') === 'Attach',
+    );
+    expect(attachBtn).toHaveAttribute('data-action', 'attach');
+  });
+
+  it('clicking a custom action button calls onAction with the action id', () => {
+    const onAction = vi.fn();
+    const { getAllByRole } = render(() => (
+      <DefaultPromptInput {...baseProps} toolbarActions={ACTIONS} onAction={onAction} />
+    ));
+    const attachBtn = getAllByRole('button').find(
+      (b) => b.getAttribute('aria-label') === 'Attach',
+    )!;
+    fireEvent.click(attachBtn);
+    expect(onAction).toHaveBeenCalledOnce();
+    expect(onAction).toHaveBeenCalledWith('attach');
+  });
+
+  it('clicking the second action button fires onAction with its id', () => {
+    const onAction = vi.fn();
+    const { getAllByRole } = render(() => (
+      <DefaultPromptInput {...baseProps} toolbarActions={ACTIONS} onAction={onAction} />
+    ));
+    const bookmarkBtn = getAllByRole('button').find(
+      (b) => b.getAttribute('aria-label') === 'Bookmark',
+    )!;
+    fireEvent.click(bookmarkBtn);
+    expect(onAction).toHaveBeenCalledWith('bookmark');
+  });
+
+  it('clicking a custom action does NOT call onSubmit', () => {
+    const onSubmit = vi.fn();
+    const onAction = vi.fn();
+    const { getAllByRole } = render(() => (
+      <DefaultPromptInput
+        {...baseProps}
+        onSubmit={onSubmit}
+        toolbarActions={ACTIONS}
+        onAction={onAction}
+      />
+    ));
+    const attachBtn = getAllByRole('button').find(
+      (b) => b.getAttribute('aria-label') === 'Attach',
+    )!;
+    fireEvent.click(attachBtn);
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+
+  it('renders a label-only button when the icon name is unknown', () => {
+    const unknownIconAction: CustomAction[] = [
+      { id: 'mystery', label: 'Mystery', icon: 'not-a-real-icon' },
+    ];
+    const { getByRole } = render(() => (
+      <DefaultPromptInput {...baseProps} toolbarActions={unknownIconAction} />
+    ));
+    // aria-label is still set to the label
+    const btn = getByRole('button', { name: 'Mystery' });
+    expect(btn).toBeInTheDocument();
+  });
+});

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

@@ -0,0 +1,331 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount } from 'solid-js';
+import './register'; // side effect: registers <kai-chat>, <kai-conversations>, <kai-prompt-input>
+import type { AttachmentData } from '../components/attachments';
+import { argTypesFor, specDescription } from '../stories/docs/element-controls';
+
+// 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-prompt-input': JSX.HTMLAttributes<HTMLElement>;
+      'kai-action': JSX.HTMLAttributes<HTMLElement> & { icon?: string; tooltip?: string };
+      'kai-slash-command': JSX.HTMLAttributes<HTMLElement> & { command?: string; description?: string; category?: string };
+    }
+  }
+}
+
+const sampleSuggestions: string[] = [
+  'Summarize this thread',
+  'Draft a reply',
+  '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 `<kai-prompt-input>` custom element (Shadow DOM and all). */
+function PromptInputElement(props: { search?: boolean; voice?: boolean; attachments?: AttachmentData[]; args?: Record<string, unknown> }) {
+  let el: PromptInputEl | undefined;
+  onMount(() => {
+    if (!el) return;
+    // Default fixed data
+    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;
+    // Scalar args from Controls
+    const args = props.args;
+    if (args) {
+      const scalarNames = [
+        'value', 'placeholder', 'disabled', 'loading', 'suggestionMode',
+        'slashCompact', 'search', 'voice',
+      ];
+      for (const name of scalarNames) {
+        if (name in args) (el as unknown as Record<string, unknown>)[name] = args[name];
+      }
+    }
+    el.addEventListener('kai-search', () => console.log('search clicked'));
+    el.addEventListener('kai-voice', () => console.log('voice clicked'));
+  });
+  return (
+    <kai-prompt-input
+      ref={(e) => (el = e as PromptInputEl)}
+      style={{ display: 'block', width: '100%', padding: '16px' }}
+    />
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kai-prompt-input id="input" style="display:block; width:100%;"></kai-prompt-input>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';   // registers the custom elements
+
+  const input = document.getElementById('input');
+  input.placeholder = 'Ask anything...';
+  input.suggestions = ['Summarize this thread', 'Draft a reply'];
+  // input.loading = true;   // shows the busy state while a response streams
+  // input.disabled = true;  // blocks typing and submit
+
+  // events are CustomEvents on the element (they do not bubble)
+  input.addEventListener('kai-submit', (e) => console.log('send:', e.detail.value));
+  input.addEventListener('kai-value-change', (e) => console.log('typing:', e.detail.value));
+  input.addEventListener('kai-suggestion-click', (e) => console.log('picked:', e.detail.value));
+</script>`;
+
+const SOLID_SNIPPET = `import '@kitn.ai/ui/elements'; // registers the custom elements
+import { onMount } from 'solid-js';
+
+function Composer() {
+  let el: HTMLElement & {
+    value?: string;
+    placeholder?: string;
+    disabled?: boolean;
+    loading?: boolean;
+    suggestions?: string[];
+  };
+  onMount(() => {
+    el.placeholder = 'Ask anything...';
+    el.suggestions = ['Summarize this thread', 'Draft a reply'];
+  });
+  return (
+    <kai-prompt-input
+      ref={el}
+      style={{ display: 'block', width: '100%' }}
+      on:kai-submit={(e) => console.log('send:', e.detail.value)}
+      on:kai-value-change={(e) => console.log('typing:', e.detail.value)}
+      on:kai-suggestion-click={(e) => console.log('picked:', e.detail.value)}
+    />
+  );
+}`;
+
+const meta = {
+  title: 'Components/PromptInput',
+  tags: ['autodocs'],
+  argTypes: argTypesFor('kai-prompt-input'),
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: specDescription('kai-prompt-input', [
+          '`<kai-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 \'@kitn.ai/ui/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** (`kai-submit`, `kai-value-change`, `kai-suggestion-click`, `kai-search`, `kai-voice`) directly on the element. Leave `value` unset to let the element manage its own input state; seed `attachments` to pre-populate staged files. **Custom toolbar buttons:** place `<kai-action id icon tooltip>` elements as children — they are invisible data carriers (Shadow DOM hides them) that the element reads and renders as extra ghost icon buttons in the left toolbar. Each click fires a `kai-toolbar-action` CustomEvent with `detail.action` equal to the action id (the same `<kai-action>` descriptor element that `<kai-message>` uses — composition symmetry).',
+          '**Slash commands (declarative):** place `<kai-slash-command command="id" description="…">Label</kai-slash-command>` elements as children — invisible data carriers merged with the `slashCommands` JS property. Typing `/` opens the palette with the combined list; selecting an item fires `kai-slash-select` with `detail.command`. Prop items appear first; declarative children are appended.',
+          '**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.',
+        ]),
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** The element used the plain-HTML / any-framework way. */
+export const Default: Story = {
+  args: {
+    placeholder: 'Send a message...',
+    disabled: false,
+    loading: false,
+    suggestionMode: 'submit',
+    slashCompact: false,
+    search: false,
+    voice: false,
+  },
+  render: (args: Record<string, unknown>) => <PromptInputElement args={args} />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** The same element used inside a SolidJS component (properties via `ref`, events via `on:`). */
+export const InSolidJS: Story = {
+  name: 'In SolidJS',
+  render: () => <PromptInputElement />,
+  parameters: { docs: { source: { code: SOLID_SNIPPET, language: 'tsx' } } },
+};
+
+const TOOLBAR_SNIPPET = `<!-- show the Search (Globe) + Voice (Mic) toolbar buttons -->
+<kai-prompt-input id="input" search voice></kai-prompt-input>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';
+  const input = document.getElementById('input');
+  input.addEventListener('kai-search', () => console.log('search clicked'));
+  input.addEventListener('kai-voice', () => console.log('voice clicked'));
+</script>`;
+
+/** With the **microphone** (and search) toolbar buttons enabled via the `voice`
+ *  and `search` flags. Clicking them fires `kai-voice` / `kai-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 -->
+<kai-prompt-input id="input" voice></kai-prompt-input>
+
+<script type="module">
+  import '@kitn.ai/ui/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' } } },
+};
+
+const CUSTOM_TOOLBAR_SNIPPET = `<kai-prompt-input id="input" voice></kai-prompt-input>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';
+
+  const input = document.getElementById('input');
+
+  // Inject <kai-action> children as toolbar buttons (declarative composition).
+  ['attach', 'translate', 'bookmark'].forEach((id, i) => {
+    const el = document.createElement('kai-action');
+    el.id = id;
+    el.setAttribute('icon', ['paperclip', 'flag', 'bookmark'][i]);
+    el.setAttribute('tooltip', ['Attach', 'Translate', 'Bookmark'][i]);
+    input.appendChild(el);
+  });
+
+  input.addEventListener('kai-toolbar-action', (e) => {
+    console.log('toolbar action:', e.detail.action);
+  });
+  input.addEventListener('kai-submit', (e) => console.log('submit:', e.detail.value));
+</script>`;
+
+const SLASH_COMMAND_SNIPPET = `<kai-prompt-input id="input" style="display:block; width:100%;"></kai-prompt-input>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';
+
+  const input = document.getElementById('input');
+
+  // Inject <kai-slash-command> children — invisible data carriers read via
+  // querySelectorAll + MutationObserver, merged with any slashCommands property.
+  [
+    { command: 'summarize', description: 'Summarize the thread' },
+    { command: 'translate', description: 'Translate to English' },
+    { command: 'explain',   description: "Explain like I'm five" },
+  ].forEach(({ command, description }) => {
+    const el = document.createElement('kai-slash-command');
+    el.setAttribute('command', command);
+    el.setAttribute('description', description);
+    el.textContent = command; // becomes the label
+    input.appendChild(el);
+  });
+
+  input.addEventListener('kai-slash-select', (e) => {
+    console.log('slash selected:', e.detail.command);
+  });
+</script>`;
+
+/** Composition: place **`<kai-action>`** children inside `<kai-prompt-input>` to add
+ *  custom ghost icon buttons in the toolbar. Each click fires a `kai-toolbar-action` event
+ *  with `detail.action` equal to the action id — the same `<kai-action>` descriptor
+ *  element that `<kai-message>` uses for its action bar (composition symmetry). */
+export const WithCustomToolbarActions: Story = {
+  name: 'Custom Toolbar Actions (kai-action)',
+  render: () => {
+    let el: HTMLElement | undefined;
+    onMount(() => {
+      if (!el) return;
+      el.setAttribute('placeholder', 'Ask anything...');
+      el.addEventListener('kai-toolbar-action', (e: Event) => {
+        console.log('toolbar action:', (e as CustomEvent<{ action: string }>).detail.action);
+      });
+    });
+    return (
+      <div style={{ padding: '16px', width: '100%' }}>
+        <kai-prompt-input
+          ref={(e: HTMLElement) => (el = e)}
+          style={{ display: 'block', width: '100%' }}
+        >
+          {/* <kai-action> children are invisible data carriers — Shadow DOM hides them.
+              The element reads them via querySelectorAll + MutationObserver and renders
+              a ghost icon button per entry in the left toolbar. Clicking fires kai-action. */}
+          <kai-action id="attach" icon="paperclip" tooltip="Attach" />
+          <kai-action id="translate" icon="flag" tooltip="Translate" />
+          <kai-action id="bookmark" icon="bookmark" tooltip="Bookmark" />
+        </kai-prompt-input>
+        <p style={{ 'margin-top': '8px', 'font-size': '12px', color: 'var(--color-muted-foreground)' }}>
+          Open the browser console to see <code>kai-action</code> events when you click the extra toolbar buttons.
+        </p>
+      </div>
+    );
+  },
+  parameters: { docs: { source: { code: CUSTOM_TOOLBAR_SNIPPET, language: 'html' } } },
+};
+
+/** Composition: place **`<kai-slash-command>`** children inside `<kai-prompt-input>`
+ *  to declare slash commands without setting the `slashCommands` JS property.
+ *  Type `/` in the input to open the palette. Each `<kai-slash-command>` child maps:
+ *  `command` attr → id, textContent → label, `description` attr → description.
+ *  Selection fires `kai-slash-select` with `detail.command`.
+ *  Prop (`slashCommands`) and declarative children are merged — prop items first. */
+export const DeclarativeSlashCommands: Story = {
+  name: 'Declarative Slash Commands (kai-slash-command)',
+  render: () => {
+    let el: HTMLElement | undefined;
+    onMount(() => {
+      if (!el) return;
+      el.setAttribute('placeholder', 'Type / to open the command palette…');
+      el.addEventListener('kai-slash-select', (e: Event) => {
+        console.log('slash selected:', (e as CustomEvent<{ command: unknown }>).detail.command);
+      });
+    });
+    return (
+      <div style={{ padding: '16px', width: '100%' }}>
+        <kai-prompt-input
+          ref={(e: HTMLElement) => (el = e)}
+          style={{ display: 'block', width: '100%' }}
+        >
+          {/* <kai-slash-command> children are invisible data carriers — Shadow DOM hides them.
+              The element reads them via querySelectorAll + MutationObserver.
+              command attr → id, textContent → label, description attr → description. */}
+          <kai-slash-command command="summarize" description="Summarize the thread">summarize</kai-slash-command>
+          <kai-slash-command command="translate" description="Translate to English">translate</kai-slash-command>
+          <kai-slash-command command="explain" description="Explain like I'm five">explain</kai-slash-command>
+        </kai-prompt-input>
+        <p style={{ 'margin-top': '8px', 'font-size': '12px', color: 'var(--color-muted-foreground)' }}>
+          Type <code>/</code> in the input to open the command palette. Open the browser
+          console to see <code>kai-slash-select</code> events on selection.
+        </p>
+      </div>
+    );
+  },
+  parameters: { docs: { source: { code: SLASH_COMMAND_SNIPPET, language: 'html' } } },
+};
+