@kitnai/chat 0.6.0 → 0.7.0

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

@@ -1,6 +1,8 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { onMount } from 'solid-js';
 import './register'; // side effect: registers the custom elements
+import { ElementSpec } from '../stories/docs/element-spec';
+import { argTypesFor } from '../stories/docs/element-controls';
 
 // The web components are custom DOM elements, so declare the tags for JSX.
 declare module 'solid-js' {
@@ -49,6 +51,7 @@ const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
 const meta = {
   title: 'Web Components/kitn-message-skills',
   tags: ['autodocs'],
+  argTypes: argTypesFor('kitn-message-skills'),
   parameters: {
     layout: 'fullscreen',
     docs: {
@@ -67,6 +70,12 @@ const meta = {
 export default meta;
 type Story = StoryObj;
 
+/** Full generated API reference — properties, events, tokens, and composed-from. */
+export const API: Story = {
+  render: () => <ElementSpec tag="kitn-message-skills" />,
+  parameters: { layout: 'padded' },
+};
+
 /** Two active-skill badges. */
 export const Default: Story = {
   render: () => <MessageSkillsElement skills={sampleSkills} />,

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

@@ -2,6 +2,8 @@ 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 { ElementSpec } from '../stories/docs/element-spec';
+import { argTypesFor } from '../stories/docs/element-controls';
 
 // The web components are custom DOM elements, so declare the tags for JSX.
 declare module 'solid-js' {
@@ -75,6 +77,7 @@ const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
 const meta = {
   title: 'Web Components/kitn-message',
   tags: ['autodocs'],
+  argTypes: argTypesFor('kitn-message'),
   parameters: {
     layout: 'fullscreen',
     docs: {
@@ -93,6 +96,12 @@ const meta = {
 export default meta;
 type Story = StoryObj;
 
+/** Full generated API reference — properties, events, tokens, and composed-from. */
+export const API: Story = {
+  render: () => <ElementSpec tag="kitn-message" />,
+  parameters: { layout: 'padded' },
+};
+
 /** A rich assistant message: markdown, reasoning, a tool call, an attachment, and actions. */
 export const Assistant: Story = {
   render: () => <MessageElement message={assistantMessage} />,

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

@@ -2,6 +2,8 @@ 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 { ElementSpec } from '../stories/docs/element-spec';
+import { argTypesFor } from '../stories/docs/element-controls';
 
 // The web components are custom DOM elements, so declare the tags for JSX.
 declare module 'solid-js' {
@@ -55,6 +57,7 @@ const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
 const meta = {
   title: 'Web Components/kitn-model-switcher',
   tags: ['autodocs'],
+  argTypes: argTypesFor('kitn-model-switcher'),
   parameters: {
     layout: 'fullscreen',
     docs: {
@@ -73,6 +76,12 @@ const meta = {
 export default meta;
 type Story = StoryObj;
 
+/** Full generated API reference — properties, events, tokens, and composed-from. */
+export const API: Story = {
+  render: () => <ElementSpec tag="kitn-model-switcher" />,
+  parameters: { layout: 'padded' },
+};
+
 /** A three-model picker; selecting updates the trigger label. */
 export const Default: Story = {
   render: () => <SwitcherElement models={models} current="opus" />,

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

@@ -2,6 +2,8 @@ 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';
+import { ElementSpec } from '../stories/docs/element-spec';
+import { argTypesFor } from '../stories/docs/element-controls';
 
 // The web components are custom DOM elements, so declare the tags for JSX.
 declare module 'solid-js' {
@@ -41,15 +43,27 @@ interface PromptInputEl extends HTMLElement {
 }
 
 /** Live demo of the actual `<kitn-prompt-input>` custom element (Shadow DOM and all). */
-function PromptInputElement(props?: { search?: boolean; voice?: boolean; attachments?: AttachmentData[] }) {
+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'));
   });
@@ -108,6 +122,7 @@ function Composer() {
 const meta = {
   title: 'Web Components/kitn-prompt-input',
   tags: ['autodocs'],
+  argTypes: argTypesFor('kitn-prompt-input'),
   parameters: {
     layout: 'fullscreen',
     docs: {
@@ -129,7 +144,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' } } },
 };
 
@@ -179,3 +203,9 @@ export const WithAttachments: Story = {
   render: () => <PromptInputElement voice attachments={sampleAttachments} />,
   parameters: { docs: { source: { code: ATTACHMENTS_SNIPPET, language: 'html' } } },
 };
+
+/** Full generated API reference — properties, events, tokens, and the SolidJS components this element is composed from. */
+export const API: Story = {
+  render: () => <ElementSpec tag="kitn-prompt-input" />,
+  parameters: { layout: 'padded' },
+};

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

@@ -1,6 +1,8 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { onMount } from 'solid-js';
 import './register'; // side effect: registers the custom elements
+import { ElementSpec } from '../stories/docs/element-spec';
+import { argTypesFor } from '../stories/docs/element-controls';
 
 type Item = string | { label: string; value?: string };
 
@@ -62,6 +64,7 @@ const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
 const meta = {
   title: 'Web Components/kitn-prompt-suggestions',
   tags: ['autodocs'],
+  argTypes: argTypesFor('kitn-prompt-suggestions'),
   parameters: {
     layout: 'fullscreen',
     docs: {
@@ -80,6 +83,12 @@ const meta = {
 export default meta;
 type Story = StoryObj;
 
+/** Full generated API reference — properties, events, tokens, and composed-from. */
+export const API: Story = {
+  render: () => <ElementSpec tag="kitn-prompt-suggestions" />,
+  parameters: { layout: 'padded' },
+};
+
 /** Default outline pills, wrapping in a row. */
 export const Default: Story = {
   render: () => <SuggestionsElement suggestions={suggestions} variant="outline" />,

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

@@ -1,6 +1,8 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { onMount } from 'solid-js';
 import './register'; // side effect: registers the custom elements
+import { ElementSpec } from '../stories/docs/element-spec';
+import { argTypesFor } from '../stories/docs/element-controls';
 
 // The web components are custom DOM elements, so declare the tags for JSX.
 declare module 'solid-js' {
@@ -46,6 +48,7 @@ const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
 const meta = {
   title: 'Web Components/kitn-reasoning',
   tags: ['autodocs'],
+  argTypes: argTypesFor('kitn-reasoning'),
   parameters: {
     layout: 'fullscreen',
     docs: {
@@ -64,6 +67,12 @@ const meta = {
 export default meta;
 type Story = StoryObj;
 
+/** Full generated API reference — properties, events, tokens, and composed-from. */
+export const API: Story = {
+  render: () => <ElementSpec tag="kitn-reasoning" />,
+  parameters: { layout: 'padded' },
+};
+
 /** A collapsed reasoning block (the trigger toggles it). */
 export const Default: Story = {
   render: () => <ReasoningElement text={sampleText} />,

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

@@ -1,6 +1,8 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { onMount } from 'solid-js';
 import './register'; // side effect: registers the custom elements
+import { ElementSpec } from '../stories/docs/element-spec';
+import { argTypesFor } from '../stories/docs/element-controls';
 
 // The web components are custom DOM elements, so declare the tags for JSX.
 declare module 'solid-js' {
@@ -49,6 +51,7 @@ const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
 const meta = {
   title: 'Web Components/kitn-response-stream',
   tags: ['autodocs'],
+  argTypes: argTypesFor('kitn-response-stream'),
   parameters: {
     layout: 'fullscreen',
     docs: {
@@ -67,6 +70,12 @@ const meta = {
 export default meta;
 type Story = StoryObj;
 
+/** Full generated API reference — properties, events, tokens, and composed-from. */
+export const API: Story = {
+  render: () => <ElementSpec tag="kitn-response-stream" />,
+  parameters: { layout: 'padded' },
+};
+
 /** Typewriter reveal (the default). */
 export const Typewriter: Story = {
   render: () => <StreamElement text={STREAM_TEXT} mode="typewriter" speed={20} />,

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

@@ -1,6 +1,8 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { onMount } from 'solid-js';
 import './register'; // side effect: registers the custom elements
+import { ElementSpec } from '../stories/docs/element-spec';
+import { argTypesFor } from '../stories/docs/element-controls';
 
 // The web components are custom DOM elements, so declare the tags for JSX.
 declare module 'solid-js' {
@@ -52,6 +54,7 @@ const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
 const meta = {
   title: 'Web Components/kitn-source-list',
   tags: ['autodocs'],
+  argTypes: argTypesFor('kitn-source-list'),
   parameters: {
     layout: 'fullscreen',
     docs: {
@@ -70,6 +73,12 @@ const meta = {
 export default meta;
 type Story = StoryObj;
 
+/** Full generated API reference — properties, events, tokens, and composed-from. */
+export const API: Story = {
+  render: () => <ElementSpec tag="kitn-source-list" />,
+  parameters: { layout: 'padded' },
+};
+
 /** Two citations rendered as a wrapped list with favicons. */
 export const Default: Story = {
   render: () => <SourceListElement />,

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

@@ -1,6 +1,8 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { onMount } from 'solid-js';
 import './register'; // side effect: registers the custom elements
+import { ElementSpec } from '../stories/docs/element-spec';
+import { argTypesFor } from '../stories/docs/element-controls';
 
 // The web components are custom DOM elements, so declare the tags for JSX.
 declare module 'solid-js' {
@@ -48,6 +50,7 @@ const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
 const meta = {
   title: 'Web Components/kitn-source',
   tags: ['autodocs'],
+  argTypes: argTypesFor('kitn-source'),
   parameters: {
     layout: 'fullscreen',
     docs: {
@@ -66,6 +69,12 @@ const meta = {
 export default meta;
 type Story = StoryObj;
 
+/** Full generated API reference — properties, events, tokens, and composed-from. */
+export const API: Story = {
+  render: () => <ElementSpec tag="kitn-source" />,
+  parameters: { layout: 'padded' },
+};
+
 /** A citation with a custom label, hover headline/description, and favicon. */
 export const Default: Story = {
   render: () => (

package/src/elements/kitn-text-shimmer.stories.tsx

@@ -1,5 +1,7 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import './register'; // side effect: registers the custom elements
+import { ElementSpec } from '../stories/docs/element-spec';
+import { argTypesFor } from '../stories/docs/element-controls';
 
 // The web components are custom DOM elements, so declare the tags for JSX.
 declare module 'solid-js' {
@@ -25,6 +27,7 @@ const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
 const meta = {
   title: 'Web Components/kitn-text-shimmer',
   tags: ['autodocs'],
+  argTypes: argTypesFor('kitn-text-shimmer'),
   parameters: {
     layout: 'fullscreen',
     docs: {
@@ -43,6 +46,12 @@ const meta = {
 export default meta;
 type Story = StoryObj;
 
+/** Full generated API reference — properties, events, tokens, and composed-from. */
+export const API: Story = {
+  render: () => <ElementSpec tag="kitn-text-shimmer" />,
+  parameters: { layout: 'padded' },
+};
+
 /** Default shimmer. */
 export const Default: Story = {
   render: () => (

package/src/elements/kitn-thinking-bar.stories.tsx

@@ -1,5 +1,7 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import './register'; // side effect: registers the custom elements
+import { ElementSpec } from '../stories/docs/element-spec';
+import { argTypesFor } from '../stories/docs/element-controls';
 
 // The web components are custom DOM elements, so declare the tags for JSX.
 declare module 'solid-js' {
@@ -29,6 +31,7 @@ const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
 const meta = {
   title: 'Web Components/kitn-thinking-bar',
   tags: ['autodocs'],
+  argTypes: argTypesFor('kitn-thinking-bar'),
   parameters: {
     layout: 'fullscreen',
     docs: {
@@ -47,6 +50,12 @@ const meta = {
 export default meta;
 type Story = StoryObj;
 
+/** Full generated API reference — properties, events, tokens, and composed-from. */
+export const API: Story = {
+  render: () => <ElementSpec tag="kitn-thinking-bar" />,
+  parameters: { layout: 'padded' },
+};
+
 /** A plain thinking indicator. */
 export const Default: Story = {
   render: () => (

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

@@ -2,6 +2,8 @@ import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { onMount } from 'solid-js';
 import './register'; // side effect: registers the custom elements
 import type { ToolPart } from '../components/tool';
+import { ElementSpec } from '../stories/docs/element-spec';
+import { argTypesFor } from '../stories/docs/element-controls';
 
 // The web components are custom DOM elements, so declare the tags for JSX.
 declare module 'solid-js' {
@@ -58,6 +60,7 @@ const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
 const meta = {
   title: 'Web Components/kitn-tool',
   tags: ['autodocs'],
+  argTypes: argTypesFor('kitn-tool'),
   parameters: {
     layout: 'fullscreen',
     docs: {
@@ -76,6 +79,12 @@ const meta = {
 export default meta;
 type Story = StoryObj;
 
+/** Full generated API reference — properties, events, tokens, and composed-from. */
+export const API: Story = {
+  render: () => <ElementSpec tag="kitn-tool" />,
+  parameters: { layout: 'padded' },
+};
+
 /** A completed call with input and output, started expanded. */
 export const Completed: Story = {
   render: () => <ToolElement tool={completedTool} open />,

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

@@ -1,6 +1,8 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { onMount } from 'solid-js';
 import './register'; // side effect: registers the custom elements
+import { ElementSpec } from '../stories/docs/element-spec';
+import { argTypesFor } from '../stories/docs/element-controls';
 
 // The web components are custom DOM elements, so declare the tags for JSX.
 declare module 'solid-js' {
@@ -57,6 +59,7 @@ const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
 const meta = {
   title: 'Web Components/kitn-voice-input',
   tags: ['autodocs'],
+  argTypes: argTypesFor('kitn-voice-input'),
   parameters: {
     layout: 'fullscreen',
     docs: {
@@ -75,6 +78,12 @@ const meta = {
 export default meta;
 type Story = StoryObj;
 
+/** Full generated API reference — properties, events, tokens, and composed-from. */
+export const API: Story = {
+  render: () => <ElementSpec tag="kitn-voice-input" />,
+  parameters: { layout: 'padded' },
+};
+
 /** A working mic button wired to a stub transcriber. */
 export const Default: Story = {
   render: () => <VoiceElement />,

package/src/elements/prompt-input.tsx

@@ -51,9 +51,9 @@ 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', {

package/src/stories/docs/element-controls.ts

@@ -0,0 +1,28 @@
+import meta from '../../elements/element-meta.json';
+
+type Prop = { name: string; type: string; default?: string; scalar: boolean };
+type ElementMeta = { tag: string; props: Prop[] };
+const all = meta as unknown as ElementMeta[];
+
+const enumValues = (type: string): string[] | null => {
+  // string-literal unions like "'light' | 'dark' | 'auto'"
+  const parts = type.split('|').map((s) => s.trim());
+  if (parts.length > 1 && parts.every((p) => /^'[^']*'$/.test(p))) return parts.map((p) => p.slice(1, -1));
+  return null;
+};
+
+/** Storybook argTypes for an element's scalar props (theme select, booleans, text, number). */
+export function argTypesFor(tag: string): Record<string, unknown> {
+  const el = all.find((e) => e.tag === tag);
+  if (!el) return {};
+  const out: Record<string, unknown> = {};
+  for (const p of el.props) {
+    if (!p.scalar) continue;
+    const values = enumValues(p.type);
+    if (values) out[p.name] = { control: 'select', options: values };
+    else if (/boolean/.test(p.type)) out[p.name] = { control: 'boolean' };
+    else if (/number/.test(p.type)) out[p.name] = { control: 'number' };
+    else out[p.name] = { control: 'text' };
+  }
+  return out;
+}

package/src/stories/docs/element-spec.tsx

@@ -0,0 +1,86 @@
+import { For, Show } from 'solid-js';
+import meta from '../../elements/element-meta.json';
+
+type Prop = { name: string; type: string; default?: string; scalar: boolean; description: string };
+type Event = { name: string; detail: string | null; description: string };
+type Composed = { name: string; group: string; storyId?: string };
+type ElementMeta = { tag: string; className: string; props: Prop[]; events: Event[]; composedFrom: Composed[]; tokens: string[] };
+
+const all = meta as unknown as ElementMeta[];
+
+const th = 'text-left font-semibold px-2 py-1.5 border-b border-border text-foreground';
+const td = 'px-2 py-1.5 border-b border-border align-top text-muted-foreground';
+const code = 'font-mono text-[0.85em] text-code-foreground';
+
+export function ElementSpec(props: { tag: string }) {
+  const el = () => all.find((e) => e.tag === props.tag);
+  return (
+    <Show when={el()} fallback={<p>Unknown element: {props.tag}</p>}>
+      {(e) => (
+        <div class="text-sm space-y-6">
+          <section>
+            <h3 class="text-title font-semibold text-foreground mb-2">Properties</h3>
+            <table class="w-full border-collapse">
+              <thead><tr><th class={th}>Property</th><th class={th}>Attribute</th><th class={th}>Type / values</th><th class={th}>Default</th></tr></thead>
+              <tbody>
+                <For each={e().props}>{(p) => (
+                  <tr>
+                    <td class={td}><span class={code}>{p.name}</span></td>
+                    <td class={td}>{p.scalar ? <span class={code}>{kebab(p.name)}</span> : <span class="opacity-50">— (property only)</span>}</td>
+                    <td class={td}><span class={code}>{p.type}</span></td>
+                    <td class={td}>{p.default ? <span class={code}>{p.default}</span> : '—'}</td>
+                  </tr>
+                )}</For>
+              </tbody>
+            </table>
+          </section>
+
+          <Show when={e().events.length}>
+            <section>
+              <h3 class="text-title font-semibold text-foreground mb-2">Events</h3>
+              <p class="text-muted-foreground mb-2 text-xs">Non-bubbling <span class={code}>CustomEvent</span>s on the element; the payload is on <span class={code}>event.detail</span>.</p>
+              <table class="w-full border-collapse">
+                <thead><tr><th class={th}>Event</th><th class={th}>detail</th><th class={th}>Description</th></tr></thead>
+                <tbody>
+                  <For each={e().events}>{(ev) => (
+                    <tr>
+                      <td class={td}><span class={code}>{ev.name}</span></td>
+                      <td class={td}><span class={code}>{detailText(ev.detail)}</span></td>
+                      <td class={td}>{ev.description}</td>
+                    </tr>
+                  )}</For>
+                </tbody>
+              </table>
+            </section>
+          </Show>
+
+          <Show when={e().composedFrom.length}>
+            <section>
+              <h3 class="text-title font-semibold text-foreground mb-2">Composed from</h3>
+              <p class="text-muted-foreground mb-2 text-xs">This element wraps these SolidJS components:</p>
+              <div class="flex flex-wrap gap-2">
+                <For each={e().composedFrom}>{(c) => (
+                  <a class="rounded-md bg-muted px-2 py-1 text-xs text-foreground hover:bg-accent no-underline" href={`?path=/docs/${c.storyId}`}>
+                    {c.group}/{c.name}
+                  </a>
+                )}</For>
+              </div>
+            </section>
+          </Show>
+
+          <section>
+            <h3 class="text-title font-semibold text-foreground mb-2">Theming</h3>
+            <p class="text-muted-foreground text-xs">
+              Themed by the global design tokens — override any <span class={code}>--color-*</span> token to rebrand (see the <a href="?path=/docs/theming-token-reference--docs" class="text-primary">Token Reference</a>).
+              <Show when={e().tokens.length}>{' '}This element also reads:{' '}<For each={e().tokens}>{(t, i) => <><span class={code}>{t}</span>{i() < e().tokens.length - 1 ? ', ' : ''}</>}</For>.</Show>
+            </p>
+          </section>
+        </div>
+      )}
+    </Show>
+  );
+}
+
+function kebab(name: string) { return name.replace(/([A-Z])/g, '-$1').toLowerCase(); }
+// Payloadless events (no detail, or an empty `Record<string, never>`) render as a dash.
+function detailText(detail: string | null) { return !detail || detail === 'Record<string, never>' ? '—' : detail; }