@kitnai/chat 0.6.0 → 0.8.0

package/src/elements/{kitn-loader.stories.tsx → loader.stories.tsx}

@@ -1,12 +1,13 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import './register'; // side effect: registers the custom elements
+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 {
-      'kitn-loader': JSX.HTMLAttributes<HTMLElement> & {
+      'kc-loader': JSX.HTMLAttributes<HTMLElement> & {
         variant?: string;
         size?: string;
         text?: string;
@@ -16,26 +17,25 @@ declare module 'solid-js' {
 }
 
 const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
-<kitn-loader variant="dots" size="md"></kitn-loader>
+<kc-loader variant="dots" size="md"></kc-loader>
 
 <script type="module">
   import '@kitnai/chat/elements';   // registers the custom elements
 </script>`;
 
 const meta = {
-  title: 'Web Components/kitn-loader',
+  title: 'Web Components/kc-loader',
   tags: ['autodocs'],
+  argTypes: argTypesFor('kc-loader'),
   parameters: {
     layout: 'fullscreen',
     docs: {
-      description: {
-        component: [
-          '`<kitn-loader>` is the framework-agnostic **web component** for an animated busy indicator — a dozen styles (circular, dots, wave, bars, text-shimmer, …) selected via the `variant` attribute, isolated in **Shadow DOM**.',
+      description: specDescription('kc-loader', [
+          '`<kc-loader>` is the framework-agnostic **web component** for an animated busy indicator — a dozen styles (circular, dots, wave, bars, text-shimmer, …) selected via the `variant` attribute, isolated in **Shadow DOM**.',
           '**When to use:** showing a small "working" indicator anywhere outside the chat thread (toolbars, buttons, panels). In SolidJS, use the `Loader` primitive directly.',
           "**How to use:** register once with `import '@kitnai/chat/elements'`, then set `variant`, `size`, and (for text variants) `text` as plain HTML attributes.",
           'See the **Code** tab for HTML usage.',
-        ].join('\n\n'),
-      },
+        ]),
     },
   },
 } satisfies Meta;
@@ -52,7 +52,7 @@ const VARIANTS = [
 export const Default: Story = {
   render: () => (
     <div style={{ padding: '24px' }}>
-      <kitn-loader variant="circular" size="md" />
+      <kc-loader variant="circular" size="md" />
     </div>
   ),
   parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
@@ -64,7 +64,7 @@ export const AllVariants: Story = {
     <div style={{ display: 'flex', 'flex-wrap': 'wrap', gap: '32px', 'align-items': 'center', padding: '24px' }}>
       {VARIANTS.map((v) => (
         <div style={{ display: 'flex', 'flex-direction': 'column', 'align-items': 'center', gap: '8px', 'min-width': '90px' }}>
-          <kitn-loader variant={v} size="md" text="Loading" />
+          <kc-loader variant={v} size="md" text="Loading" />
           <code style={{ 'font-size': '11px', opacity: 0.6 }}>{v}</code>
         </div>
       ))}
@@ -78,7 +78,7 @@ export const Sizes: Story = {
     <div style={{ display: 'flex', gap: '32px', 'align-items': 'center', padding: '24px' }}>
       {['sm', 'md', 'lg'].map((s) => (
         <div style={{ display: 'flex', 'flex-direction': 'column', 'align-items': 'center', gap: '8px' }}>
-          <kitn-loader variant="dots" size={s} />
+          <kc-loader variant="dots" size={s} />
           <code style={{ 'font-size': '11px', opacity: 0.6 }}>{s}</code>
         </div>
       ))}

package/src/elements/loader.tsx

@@ -1,4 +1,4 @@
-import { defineKitnElement } from './define';
+import { defineWebComponent } from './define';
 import { Loader, type LoaderVariant, type LoaderSize } from '../components/loader';
 
 interface Props extends Record<string, unknown> {
@@ -13,10 +13,10 @@ interface Props extends Record<string, unknown> {
 }
 
 /**
- * `<kitn-loader>` — an animated loader. `variant` selects the style (circular,
+ * `<kc-loader>` — an animated loader. `variant` selects the style (circular,
  * dots, wave, text-shimmer, …); `size` and `text` are attributes.
  */
-defineKitnElement<Props>('kitn-loader', {
+defineWebComponent<Props>('kc-loader', {
   variant: 'circular',
   size: 'md',
   text: undefined,

package/src/elements/{kitn-markdown.stories.tsx → markdown.stories.tsx}

@@ -1,13 +1,14 @@
 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';
 
 // 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>;
+      'kc-markdown': JSX.HTMLAttributes<HTMLElement>;
     }
   }
 }
@@ -25,19 +26,19 @@ export function add(a: number, b: number): number {
 }
 \`\`\``;
 
-/** Render the actual `<kitn-markdown>` custom element with a `content` property. */
+/** Render the actual `<kc-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' }} />
+    <kc-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>
+<kc-markdown id="md" code-theme="github-dark-dimmed"></kc-markdown>
 
 <script type="module">
   import '@kitnai/chat/elements';   // registers the custom elements
@@ -48,19 +49,18 @@ const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
 </script>`;
 
 const meta = {
-  title: 'Web Components/kitn-markdown',
+  title: 'Web Components/kc-markdown',
   tags: ['autodocs'],
+  argTypes: argTypesFor('kc-markdown'),
   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**.',
+      description: specDescription('kc-markdown', [
+          '`<kc-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;

package/src/elements/markdown.tsx

@@ -1,4 +1,4 @@
-import { defineKitnElement } from './define';
+import { defineWebComponent } from './define';
 import { Markdown } from '../components/markdown';
 import { ChatConfig, useChatConfig, type ProseSize } from '../primitives/chat-config';
 
@@ -14,11 +14,11 @@ interface Props extends Record<string, unknown> {
 }
 
 /**
- * `<kitn-markdown>` — renders markdown (with fenced-code syntax highlighting) as
+ * `<kc-markdown>` — renders markdown (with fenced-code syntax highlighting) as
  * a standalone element. Content via the `content` property; sizing/highlighting
  * via attributes.
  */
-defineKitnElement<Props>('kitn-markdown', {
+defineWebComponent<Props>('kc-markdown', {
   content: '',
   proseSize: 'sm',
   codeTheme: 'github-dark-dimmed',

package/src/elements/{kitn-message-skills.stories.tsx → message-skills.stories.tsx}

@@ -1,13 +1,14 @@
 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';
 
 // 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>;
+      'kc-skills': JSX.HTMLAttributes<HTMLElement>;
     }
   }
 }
@@ -22,19 +23,19 @@ const sampleSkills: Skill[] = [
   { id: 's2', name: 'code' },
 ];
 
-/** Render the actual `<kitn-message-skills>` custom element with a `skills` property. */
+/** Render the actual `<kc-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' }} />
+    <kc-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>
+<kc-skills id="skills"></kc-skills>
 
 <script type="module">
   import '@kitnai/chat/elements';   // registers the custom elements
@@ -47,19 +48,18 @@ const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
 </script>`;
 
 const meta = {
-  title: 'Web Components/kitn-message-skills',
+  title: 'Web Components/kc-skills',
   tags: ['autodocs'],
+  argTypes: argTypesFor('kc-skills'),
   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**.',
+      description: specDescription('kc-skills', [
+          '`<kc-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;

package/src/elements/message-skills.tsx

@@ -1,4 +1,4 @@
-import { defineKitnElement } from './define';
+import { defineWebComponent } from './define';
 import { MessageSkills } from '../components/message-skills';
 
 interface Skill {
@@ -14,9 +14,9 @@ interface Props extends Record<string, unknown> {
 }
 
 /**
- * `<kitn-message-skills>` — badges showing which skills were active for a
+ * `<kc-skills>` — badges showing which skills were active for a
  * message. Data via the `skills` property.
  */
-defineKitnElement<Props>('kitn-message-skills', {
+defineWebComponent<Props>('kc-skills', {
   skills: [],
 }, (props) => <MessageSkills skills={props.skills} />);

package/src/elements/{kitn-message.stories.tsx → message.stories.tsx}

@@ -2,13 +2,14 @@ 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';
+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 {
-      'kitn-message': JSX.HTMLAttributes<HTMLElement>;
+      'kc-message': JSX.HTMLAttributes<HTMLElement>;
     }
   }
 }
@@ -17,7 +18,7 @@ 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.",
+    "Here's the plan, with a quick code sample:\n\n```js\nconst kit = useChat();\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: [
@@ -42,19 +43,19 @@ const userMessage: ChatMessage = {
   content: 'How do I compose these myself?',
 };
 
-/** Render the actual `<kitn-message>` custom element with a `message` property. */
+/** Render the actual `<kc-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' }} />
+    <kc-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>
+<kc-message id="msg" style="display:block;"></kc-message>
 
 <script type="module">
   import '@kitnai/chat/elements';   // registers the custom elements
@@ -62,7 +63,7 @@ const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
   const msg = document.getElementById('msg');
   msg.message = {
     id: 'm-a', role: 'assistant',
-    content: "Here's the plan:\\n\\n\\\`\\\`\\\`js\\nconst kit = useKitn();\\n\\\`\\\`\\\`",
+    content: "Here's the plan:\\n\\n\\\`\\\`\\\`js\\nconst kit = useChat();\\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'],
@@ -73,19 +74,18 @@ const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
 </script>`;
 
 const meta = {
-  title: 'Web Components/kitn-message',
+  title: 'Web Components/kc-message',
   tags: ['autodocs'],
+  argTypes: argTypesFor('kc-message'),
   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**.',
+      description: specDescription('kc-message', [
+          '`<kc-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 `<kc-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;

package/src/elements/message.tsx

@@ -1,5 +1,5 @@
 import { For, Show, type Component } from 'solid-js';
-import { defineKitnElement } from './define';
+import { defineWebComponent } from './define';
 import { ChatConfig, useChatConfig, type ProseSize } from '../primitives/chat-config';
 import { Message, MessageContent, MessageActions } from '../components/message';
 import { Reasoning, ReasoningTrigger, ReasoningContent } from '../components/reasoning';
@@ -26,7 +26,7 @@ interface Props extends Record<string, unknown> {
   codeHighlight?: boolean;
 }
 
-/** Events fired by `<kitn-message>`. */
+/** Events fired by `<kc-message>`. */
 interface Events {
   /** An action button was clicked. */
   messageaction: { messageId: string; action: ChatMessageAction };
@@ -40,12 +40,12 @@ const ACTION_ICON: Record<ChatMessageAction, Component<{ class?: string }>> = {
 };
 
 /**
- * `<kitn-message>` — a single message row: markdown/plain content, reasoning,
+ * `<kc-message>` — a single message row: markdown/plain content, reasoning,
  * tool calls, attachments, and action buttons, rendered from one `message`
- * object (the same shape `<kitn-chat>` uses per message). The keystone of the
+ * object (the same shape `<kc-chat>` uses per message). The keystone of the
  * "compose your own message list" pattern. Emits `messageaction`.
  */
-defineKitnElement<Props, Events>('kitn-message', {
+defineWebComponent<Props, Events>('kc-message', {
   message: undefined,
   role: 'assistant',
   content: undefined,

package/src/elements/{kitn-model-switcher.stories.tsx → model-switcher.stories.tsx}

@@ -2,13 +2,14 @@ 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';
+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 {
-      'kitn-model-switcher': JSX.HTMLAttributes<HTMLElement>;
+      'kc-model-switcher': JSX.HTMLAttributes<HTMLElement>;
     }
   }
 }
@@ -19,7 +20,7 @@ const models: ModelOption[] = [
   { id: 'haiku', name: 'Claude Haiku', provider: 'Anthropic' },
 ];
 
-/** Render `<kitn-model-switcher>` with `models` set as a property; tracks selection. */
+/** Render `<kc-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(() => {
@@ -33,12 +34,12 @@ function SwitcherElement(props: { models: ModelOption[]; current?: string }) {
     });
   });
   return (
-    <kitn-model-switcher ref={(e) => (el = e as HTMLElement)} style={{ display: 'inline-block', padding: '40px' }} />
+    <kc-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>
+<kc-model-switcher id="ms"></kc-model-switcher>
 
 <script type="module">
   import '@kitnai/chat/elements';   // registers the custom elements
@@ -53,19 +54,18 @@ const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
 </script>`;
 
 const meta = {
-  title: 'Web Components/kitn-model-switcher',
+  title: 'Web Components/kc-model-switcher',
   tags: ['autodocs'],
+  argTypes: argTypesFor('kc-model-switcher'),
   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.',
+      description: specDescription('kc-model-switcher', [
+          '`<kc-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 `<kc-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;

package/src/elements/model-switcher.tsx

@@ -1,4 +1,4 @@
-import { defineKitnElement } from './define';
+import { defineWebComponent } from './define';
 import { ModelSwitcher } from '../components/model-switcher';
 import type { ModelOption } from '../types';
 
@@ -9,21 +9,21 @@ interface Props extends Record<string, unknown> {
   currentModel?: string;
 }
 
-/** Events fired by `<kitn-model-switcher>`. */
+/** Events fired by `<kc-model-switcher>`. */
 interface Events {
   /** A model was selected. */
   modelchange: { modelId: string };
 }
 
 /**
- * `<kitn-model-switcher>` — an event-emitting leaf element. Data in via the
+ * `<kc-model-switcher>` — an event-emitting leaf element. Data in via the
  * `models` property, selection out via a `modelchange` event. Mirrors the
- * header switcher inside `<kitn-chat>` as a standalone, composable piece.
+ * header switcher inside `<kc-chat>` as a standalone, composable piece.
  *
  * Note: like the underlying primitive, this only renders when more than one
  * model is provided.
  */
-defineKitnElement<Props, Events>('kitn-model-switcher', {
+defineWebComponent<Props, Events>('kc-model-switcher', {
   models: [],
   currentModel: undefined,
 }, (props, { dispatch }) => (

package/src/elements/{kitn-prompt-input.stories.tsx → prompt-input.stories.tsx}

@@ -1,14 +1,15 @@
 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 './register'; // side effect: registers <kc-chat>, <kc-conversations>, <kc-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 {
-      'kitn-prompt-input': JSX.HTMLAttributes<HTMLElement>;
+      'kc-prompt-input': JSX.HTMLAttributes<HTMLElement>;
     }
   }
 }
@@ -40,21 +41,33 @@ interface PromptInputEl extends HTMLElement {
   attachments?: AttachmentData[];
 }
 
-/** Live demo of the actual `<kitn-prompt-input>` custom element (Shadow DOM and all). */
-function PromptInputElement(props?: { search?: boolean; voice?: boolean; attachments?: AttachmentData[] }) {
+/** Live demo of the actual `<kc-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;
+    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('search', () => console.log('search clicked'));
     el.addEventListener('voice', () => console.log('voice clicked'));
   });
   return (
-    <kitn-prompt-input
+    <kc-prompt-input
       ref={(e) => (el = e as PromptInputEl)}
       style={{ display: 'block', width: '100%', padding: '16px' }}
     />
@@ -62,7 +75,7 @@ function PromptInputElement(props?: { search?: boolean; voice?: boolean; attachm
 }
 
 const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
-<kitn-prompt-input id="input" style="display:block; width:100%;"></kitn-prompt-input>
+<kc-prompt-input id="input" style="display:block; width:100%;"></kc-prompt-input>
 
 <script type="module">
   import '@kitnai/chat/elements';   // registers the custom elements
@@ -95,7 +108,7 @@ function Composer() {
     el.suggestions = ['Summarize this thread', 'Draft a reply'];
   });
   return (
-    <kitn-prompt-input
+    <kc-prompt-input
       ref={el}
       style={{ display: 'block', width: '100%' }}
       on:submit={(e) => console.log('send:', e.detail.value)}
@@ -106,20 +119,19 @@ function Composer() {
 }`;
 
 const meta = {
-  title: 'Web Components/kitn-prompt-input',
+  title: 'Web Components/kc-prompt-input',
   tags: ['autodocs'],
+  argTypes: argTypesFor('kc-prompt-input'),
   parameters: {
     layout: 'fullscreen',
     docs: {
-      description: {
-        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.',
+      description: specDescription('kc-prompt-input', [
+          '`<kc-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`, `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'),
-      },
+        ]),
     },
   },
 } satisfies Meta;
@@ -129,7 +141,16 @@ type Story = StoryObj;
 
 /** The element used the plain-HTML / any-framework way. */
 export const Default: Story = {
-  render: () => <PromptInputElement />,
+  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' } } },
 };
 
@@ -141,7 +162,7 @@ export const InSolidJS: Story = {
 };
 
 const TOOLBAR_SNIPPET = `<!-- show the Search (Globe) + Voice (Mic) toolbar buttons -->
-<kitn-prompt-input id="input" search voice></kitn-prompt-input>
+<kc-prompt-input id="input" search voice></kc-prompt-input>
 
 <script type="module">
   import '@kitnai/chat/elements';
@@ -159,7 +180,7 @@ export const WithVoiceAndSearch: Story = {
 };
 
 const ATTACHMENTS_SNIPPET = `<!-- seed staged attachments without an upload -->
-<kitn-prompt-input id="input" voice></kitn-prompt-input>
+<kc-prompt-input id="input" voice></kc-prompt-input>
 
 <script type="module">
   import '@kitnai/chat/elements';
@@ -179,3 +200,4 @@ export const WithAttachments: Story = {
   render: () => <PromptInputElement voice attachments={sampleAttachments} />,
   parameters: { docs: { source: { code: ATTACHMENTS_SNIPPET, language: 'html' } } },
 };
+

package/src/elements/prompt-input.tsx

@@ -1,5 +1,5 @@
 import { createEffect, createSignal } from 'solid-js';
-import { defineKitnElement } from './define';
+import { defineWebComponent } from './define';
 import { DefaultPromptInput } from './default-input';
 import type { AttachmentData } from '../components/attachments';
 import type { SlashCommandItem } from '../components/slash-command';
@@ -40,7 +40,7 @@ interface Props extends Record<string, unknown> {
   attachments?: AttachmentData[];
 }
 
-/** Events fired by `<kitn-prompt-input>`. */
+/** Events fired by `<kc-prompt-input>`. */
 interface Events {
   /** The user submitted the prompt (Enter or send button) with its attachments. */
   submit: { value: string; attachments: AttachmentData[] };
@@ -51,12 +51,12 @@ interface Events {
   /** A slash command was chosen from the palette. */
   slashselect: { command: SlashCommandItem };
   /** The Search (Globe) toolbar button was clicked. */
-  search: undefined;
+  search: Record<string, never>;
   /** The Voice (Mic) toolbar button was clicked. */
-  voice: undefined;
+  voice: Record<string, never>;
 }
 
-defineKitnElement<Props, Events>('kitn-prompt-input', {
+defineWebComponent<Props, Events>('kc-prompt-input', {
   value: undefined,
   placeholder: 'Send a message...',
   disabled: false,