@kitnai/chat 0.3.1 → 0.5.0

package/src/elements/feedback-bar.tsx

@@ -0,0 +1,33 @@
+import { defineKitnElement } from './define';
+import { FeedbackBar } from '../components/feedback-bar';
+
+interface Props extends Record<string, unknown> {
+  /** The banner label (e.g. "Was this helpful?"). Attribute: `bar-title`
+   *  (`title` is avoided — it's a global HTML attribute). */
+  barTitle?: string;
+}
+
+/** Events fired by `<kitn-feedback-bar>`. */
+interface Events {
+  /** The user clicked thumbs-up. */
+  helpful: void;
+  /** The user clicked thumbs-down. */
+  nothelpful: void;
+  /** The user dismissed the banner. */
+  close: void;
+}
+
+/**
+ * `<kitn-feedback-bar>` — an inline thumbs up/down feedback banner. Emits
+ * `helpful` / `nothelpful` / `close`.
+ */
+defineKitnElement<Props, Events>('kitn-feedback-bar', {
+  barTitle: 'Was this helpful?',
+}, (props, { dispatch }) => (
+  <FeedbackBar
+    title={props.barTitle}
+    onHelpful={() => dispatch('helpful')}
+    onNotHelpful={() => dispatch('nothelpful')}
+    onClose={() => dispatch('close')}
+  />
+));

package/src/elements/file-upload.tsx

@@ -0,0 +1,44 @@
+import { defineKitnElement } from './define';
+import { FileUpload, FileUploadTrigger } from '../components/file-upload';
+import { Upload } from 'lucide-solid';
+
+interface Props extends Record<string, unknown> {
+  /** Allow selecting multiple files (default true). */
+  multiple?: boolean;
+  /** `accept` attribute for the file picker (e.g. `image/*`). */
+  accept?: string;
+  /** Disable the dropzone — no clicking, no drag-and-drop. */
+  disabled?: boolean;
+  /** Default dropzone label (overridable via the default slot). */
+  label?: string;
+}
+
+/** Events fired by `<kitn-file-upload>`. */
+interface Events {
+  /** Files were picked or dropped. */
+  filesadded: { files: File[] };
+}
+
+/**
+ * `<kitn-file-upload>` — a click/drag-drop dropzone. Emits `filesadded`. The
+ * default dropzone label can be replaced with your own markup via the default
+ * `<slot>` (a "Route 2" custom-content slot).
+ */
+defineKitnElement<Props, Events>('kitn-file-upload', {
+  multiple: true,
+  accept: undefined,
+  disabled: false,
+  label: 'Click or drop files to upload',
+}, (props, { dispatch, flag }) => (
+  <FileUpload
+    multiple={flag('multiple')}
+    accept={props.accept}
+    disabled={flag('disabled')}
+    onFilesAdded={(files) => dispatch('filesadded', { files })}
+  >
+    <FileUploadTrigger class="border-border bg-muted/30 hover:bg-muted/60 text-muted-foreground flex w-full cursor-pointer flex-col items-center justify-center gap-2 rounded-xl border border-dashed px-6 py-8 text-sm transition-colors">
+      <Upload class="size-5" />
+      <slot>{props.label}</slot>
+    </FileUploadTrigger>
+  </FileUpload>
+));

package/src/elements/image.tsx

@@ -0,0 +1,32 @@
+import { defineKitnElement } from './define';
+import { Image } from '../components/image';
+
+interface Props extends Record<string, unknown> {
+  /** Base64-encoded image data (pair with `media-type`). */
+  base64?: string;
+  /** Raw image bytes (set as a JS property). */
+  bytes?: Uint8Array;
+  /** Alt text. */
+  alt?: string;
+  /** MIME type (default `image/png`). */
+  mediaType?: string;
+}
+
+/**
+ * `<kitn-image>` — renders a base64 or byte-array image with a skeleton
+ * fallback while it resolves. `base64`/`alt`/`media-type` via attributes;
+ * `bytes` via property.
+ */
+defineKitnElement<Props>('kitn-image', {
+  base64: undefined,
+  bytes: undefined,
+  alt: '',
+  mediaType: undefined,
+}, (props) => (
+  <Image
+    alt={props.alt ?? ''}
+    base64={props.base64}
+    uint8Array={props.bytes}
+    mediaType={props.mediaType}
+  />
+));

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

@@ -0,0 +1,181 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount } from 'solid-js';
+import './register'; // side effect: registers the custom elements
+import type { AttachmentData } from '../components/attachments';
+
+// 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-attachments': JSX.HTMLAttributes<HTMLElement> & {
+        variant?: string;
+        'hover-card'?: boolean | string;
+        removable?: boolean | string;
+        'show-media-type'?: boolean | string;
+      };
+    }
+  }
+}
+
+// Mixed file/source items (icons + labels) — mirrors Components/Attachments.
+const sampleItems: AttachmentData[] = [
+  {
+    id: '1',
+    type: 'file',
+    filename: 'mountain-landscape.jpg',
+    mediaType: 'image/jpeg',
+    url: 'https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=400&h=400&fit=crop',
+  },
+  {
+    id: '2',
+    type: 'file',
+    filename: 'sunset-beach.png',
+    mediaType: 'image/png',
+    url: 'https://images.unsplash.com/photo-1507525428034-b723cf961d3e?w=400&h=400&fit=crop',
+  },
+  { id: '3', type: 'file', filename: 'architecture-report.pdf', mediaType: 'application/pdf' },
+  { id: '4', type: 'file', filename: 'demo-recording.mp4', mediaType: 'video/mp4' },
+  { id: '5', type: 'file', filename: 'podcast-episode.mp3', mediaType: 'audio/mpeg' },
+  { id: '6', type: 'source-document', filename: 'SolidJS Documentation', title: 'SolidJS Reactivity Guide', url: 'https://solidjs.com/docs' },
+];
+
+// Image-only items — used for the grid thumbnails + hover-card preview stories.
+const imageItems: AttachmentData[] = [
+  {
+    id: 'img-1',
+    type: 'file',
+    filename: 'mountain-landscape.jpg',
+    mediaType: 'image/jpeg',
+    url: 'https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=400&h=400&fit=crop',
+  },
+  {
+    id: 'img-2',
+    type: 'file',
+    filename: 'sunset-beach.png',
+    mediaType: 'image/png',
+    url: 'https://images.unsplash.com/photo-1507525428034-b723cf961d3e?w=400&h=400&fit=crop',
+  },
+];
+
+/** Render `<kitn-attachments>` with an `items` property and the given flags. */
+function AttachmentsElement(props: {
+  items: AttachmentData[];
+  variant?: string;
+  removable?: boolean;
+  hoverCard?: boolean;
+  showMediaType?: boolean;
+}) {
+  let el: (HTMLElement & { items?: AttachmentData[] }) | undefined;
+  onMount(() => {
+    if (!el) return;
+    el.items = props.items;
+    if (props.variant) el.setAttribute('variant', props.variant);
+    if (props.hoverCard) el.setAttribute('hover-card', '');
+    if (props.showMediaType) el.setAttribute('show-media-type', '');
+    if (props.removable) {
+      el.setAttribute('removable', '');
+      el.addEventListener('remove', ((e: CustomEvent<{ id: string }>) => {
+        el!.items = (el!.items ?? []).filter((x) => x.id !== e.detail.id);
+      }) as EventListener);
+    }
+  });
+  return (
+    <kitn-attachments
+      ref={(e) => (el = e as HTMLElement)}
+      style={{ display: 'block', padding: '24px', 'max-width': '720px' }}
+    />
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-attachments id="att" variant="grid" removable></kitn-attachments>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  const att = document.getElementById('att');
+  att.items = [
+    { id: '1', type: 'file', filename: 'mountain-landscape.jpg',
+      mediaType: 'image/jpeg', url: 'https://.../mountain.jpg' },
+    { id: '2', type: 'file', filename: 'spec.pdf', mediaType: 'application/pdf' },
+  ];
+
+  // events are CustomEvents on the element (they do not bubble)
+  att.addEventListener('remove', (e) => {
+    att.items = att.items.filter((x) => x.id !== e.detail.id);
+  });
+</script>`;
+
+const HOVER_SNIPPET = `<!-- inline/list chips with a hover-card image preview -->
+<kitn-attachments id="att" variant="inline" hover-card></kitn-attachments>
+
+<script type="module">
+  import '@kitnai/chat/elements';
+
+  const att = document.getElementById('att');
+  // image attachments show their thumbnail in the hover card on hover;
+  // non-image attachments show their label + media type instead.
+  att.items = [
+    { id: '1', type: 'file', filename: 'mountain-landscape.jpg',
+      mediaType: 'image/jpeg', url: 'https://.../mountain.jpg' },
+  ];
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-attachments',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-attachments>` is the framework-agnostic **web component** for a set of file/source attachments, and the exemplar for the "collapse a compound primitive to ONE configurable element" pattern: the sub-parts the SolidJS layer composes become attributes here. Isolated in **Shadow DOM**.',
+          '**When to use:** rendering attachment chips/tiles in a non-Solid app. In SolidJS, compose the `Attachment*` primitives for fully custom layouts.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, set the data via the `items` **property**, pick a layout with `variant` (`grid` | `inline` | `list`), add `removable` to get per-item remove buttons (emits a `remove` **CustomEvent** with `{ id }`), and `hover-card` for inline/list previews (image attachments preview their thumbnail).",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** Visual tiles (the default `grid` variant) — image attachments render as real
+ *  `<img>` thumbnails; non-image files fall back to a media-type icon. */
+export const Grid: Story = {
+  render: () => <AttachmentsElement items={sampleItems} variant="grid" />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** Icon + label chips (`inline`) — files shown as a small preview + filename. */
+export const Inline: Story = {
+  render: () => <AttachmentsElement items={sampleItems} variant="inline" />,
+};
+
+/** Detailed rows (`list`) with the media type beneath each filename. */
+export const List: Story = {
+  render: () => <AttachmentsElement items={sampleItems} variant="list" showMediaType />,
+};
+
+/** Removable rows — clicking the remove button fires a `remove` event. */
+export const RemovableList: Story = {
+  name: 'Removable List',
+  render: () => <AttachmentsElement items={sampleItems} variant="list" removable />,
+};
+
+/** Image thumbnails in a grid (real `<img>` previews). */
+export const ImageGrid: Story = {
+  name: 'Image Grid',
+  render: () => <AttachmentsElement items={imageItems} variant="grid" />,
+};
+
+/** Inline chips with a hover-card preview — hover an image chip to see its
+ *  thumbnail enlarge in the hover card. */
+export const WithHoverCard: Story = {
+  name: 'With Hover Card',
+  render: () => <AttachmentsElement items={imageItems} variant="inline" hoverCard />,
+  parameters: { docs: { source: { code: HOVER_SNIPPET, language: 'html' } } },
+};

package/src/elements/kitn-chain-of-thought.stories.tsx

@@ -0,0 +1,75 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount } from 'solid-js';
+import './register'; // side effect: registers the custom elements
+
+interface Step {
+  label: string;
+  content?: string;
+}
+
+// The web components are custom DOM elements, so declare the tags for JSX.
+declare module 'solid-js' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace JSX {
+    interface IntrinsicElements {
+      'kitn-chain-of-thought': JSX.HTMLAttributes<HTMLElement>;
+    }
+  }
+}
+
+const steps: Step[] = [
+  { label: 'Understand the request', content: 'The user wants a composable set of web components.' },
+  { label: 'Design the API', content: 'Route 1: variant + flags + events; rich data via properties.' },
+  { label: 'Build & verify' },
+];
+
+/** Render `<kitn-chain-of-thought>` with the `steps` set as a JS property. */
+function CotElement(props: { steps: Step[] }) {
+  let el: (HTMLElement & { steps?: Step[] }) | undefined;
+  onMount(() => {
+    if (el) el.steps = props.steps;
+  });
+  return (
+    <kitn-chain-of-thought ref={(e) => (el = e as HTMLElement)} style={{ display: 'block', padding: '24px', 'max-width': '560px' }} />
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-chain-of-thought id="cot"></kitn-chain-of-thought>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  document.getElementById('cot').steps = [
+    { label: 'Understand the request', content: 'The user wants a composable set.' },
+    { label: 'Design the API', content: 'Route 1: variant + flags + events.' },
+    { label: 'Build & verify' },
+  ];
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-chain-of-thought',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-chain-of-thought>` is the framework-agnostic **web component** for step-by-step reasoning — a connected list of steps, each with optional collapsible detail — isolated in **Shadow DOM**. The compound primitive collapses to a single `steps` data model (Route 1).',
+          '**When to use:** surfacing an agent\'s plan or reasoning trace in a non-Solid app. In SolidJS, compose the `ChainOfThought` primitives for finer control.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, then set the `steps` **property** — an array of `{ label, content? }`. Steps with `content` become expandable.",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** A three-step reasoning trace; the last step has no detail. */
+export const Default: Story = {
+  render: () => <CotElement steps={steps} />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};

package/src/elements/kitn-chat-scope-picker.stories.tsx

@@ -0,0 +1,72 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount } from 'solid-js';
+import './register'; // side effect: registers the custom elements
+
+// The web components are custom DOM elements, so declare the tags for JSX.
+declare module 'solid-js' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace JSX {
+    interface IntrinsicElements {
+      'kitn-chat-scope-picker': JSX.HTMLAttributes<HTMLElement> & {
+        'current-label'?: string;
+      };
+    }
+  }
+}
+
+/** Render `<kitn-chat-scope-picker>` with author/tag options set as properties. */
+function ScopePickerElement(props: { authors: string[]; tags: string[] }) {
+  let el: (HTMLElement & { availableAuthors?: string[]; availableTags?: string[] }) | undefined;
+  onMount(() => {
+    if (!el) return;
+    el.availableAuthors = props.authors;
+    el.availableTags = props.tags;
+    el.addEventListener('scopechange', (e) => {
+      const ev = e as CustomEvent<{ filters: unknown }>;
+      console.log('scopechange', ev.detail.filters ?? 'all');
+    });
+  });
+  return (
+    <kitn-chat-scope-picker ref={(e) => (el = e as HTMLElement)} style={{ display: 'inline-block', padding: '40px' }} />
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-chat-scope-picker id="scope"></kitn-chat-scope-picker>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  const scope = document.getElementById('scope');
+  scope.availableAuthors = ['Rob', 'Alex'];
+  scope.availableTags = ['design', 'api'];
+  // undefined filters means "All Content"
+  scope.addEventListener('scopechange', (e) => console.log(e.detail.filters ?? 'all'));
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-chat-scope-picker',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-chat-scope-picker>` is the framework-agnostic **web component** for scoping a chat by author or tag — a dropdown that emits the chosen filters — isolated in **Shadow DOM**.',
+          '**When to use:** letting users narrow a conversation/search to a subset of content. In SolidJS, use the `ChatScopePicker` primitive.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, set the `availableAuthors` / `availableTags` **properties** (and optionally `current-label`), and listen for the `scopechange` **CustomEvent** (`undefined` filters = \"All Content\").",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** Authors and tags available as scope filters. */
+export const Default: Story = {
+  render: () => <ScopePickerElement authors={['Rob', 'Alex']} tags={['design', 'api']} />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};

package/src/elements/kitn-chat-workspace.stories.tsx

@@ -0,0 +1,195 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount } from 'solid-js';
+import './register'; // side effect: registers all kitn custom elements including <kitn-chat-workspace>
+import type { ConversationGroup, ConversationSummary, ModelOption } from '../types';
+import type { ChatMessage } from './chat-types';
+
+// The web components are custom DOM elements, so declare the tags for JSX.
+declare module 'solid-js' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace JSX {
+    interface IntrinsicElements {
+      'kitn-chat-workspace': JSX.HTMLAttributes<HTMLElement>;
+    }
+  }
+}
+
+const sampleGroups: ConversationGroup[] = [
+  { id: 'today', name: 'Today', sortOrder: 0, createdAt: '2026-06-13T00:00:00.000Z' },
+];
+
+const sampleConversations: ConversationSummary[] = [
+  {
+    id: '1',
+    title: 'Web component architecture',
+    groupId: 'today',
+    scope: { type: 'document' },
+    messageCount: 12,
+    lastMessageAt: '2026-06-13T15:30:00.000Z',
+    updatedAt: '2026-06-13T15:30:00.000Z',
+  },
+  {
+    id: '2',
+    title: 'Theming & tokens',
+    groupId: 'today',
+    scope: { type: 'document' },
+    messageCount: 5,
+    lastMessageAt: '2026-06-13T11:20:00.000Z',
+    updatedAt: '2026-06-13T11:20:00.000Z',
+  },
+];
+
+const sampleModels: ModelOption[] = [
+  { id: 'claude-4', name: 'Claude 4 Opus', provider: 'Anthropic' },
+  { id: 'gpt-4o', name: 'GPT-4o', provider: 'OpenAI' },
+];
+
+const sampleMessages: ChatMessage[] = [
+  { id: 'm1', role: 'user', content: 'How do I drop the whole chat app in with one tag?' },
+  {
+    id: 'm2',
+    role: 'assistant',
+    content:
+      'Use `<kitn-chat-workspace>` — set `conversations`, `messages`, and `models` as properties and listen for `conversationselect` + `submit`.',
+    actions: ['copy', 'like'],
+  },
+];
+
+/** Live demo of the actual `<kitn-chat-workspace>` custom element (Shadow DOM and all). */
+function WorkspaceElement() {
+  let el:
+    | (HTMLElement & {
+        groups?: ConversationGroup[];
+        conversations?: ConversationSummary[];
+        activeId?: string;
+        messages?: ChatMessage[];
+        models?: ModelOption[];
+        currentModel?: string;
+        chatTitle?: string;
+      })
+    | undefined;
+  onMount(() => {
+    if (el) {
+      el.groups = sampleGroups;
+      el.conversations = sampleConversations;
+      el.activeId = '1';
+      el.messages = sampleMessages;
+      el.models = sampleModels;
+      el.currentModel = 'claude-4';
+      el.chatTitle = 'Web component architecture';
+      el.addEventListener('conversationselect', (e) => console.log('select', (e as CustomEvent).detail));
+      el.addEventListener('submit', (e) => console.log('submit', (e as unknown as CustomEvent).detail));
+      el.addEventListener('sidebartoggle', (e) => console.log('sidebartoggle', (e as CustomEvent).detail));
+    }
+  });
+  return (
+    <div style={{ height: '720px', width: '100%' }}>
+      <kitn-chat-workspace
+        ref={(e) => (el = e as HTMLElement)}
+        style={{ display: 'block', height: '100%' }}
+      />
+    </div>
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-chat-workspace id="workspace" style="display:block; height:100vh;"></kitn-chat-workspace>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  const workspace = document.getElementById('workspace');
+  workspace.conversations = [
+    {
+      id: '1', title: 'Web component architecture',
+      scope: { type: 'document' }, messageCount: 12,
+      lastMessageAt: '2026-06-13T15:30:00Z', updatedAt: '2026-06-13T15:30:00Z',
+    },
+  ];
+  workspace.messages = [
+    { id: 'm1', role: 'user', content: 'How do I drop the whole chat app in with one tag?' },
+    { id: 'm2', role: 'assistant', content: 'Use <kitn-chat-workspace> — set conversations, messages, and models as properties.' },
+  ];
+  workspace.models = [
+    { id: 'claude-4', name: 'Claude 4 Opus', provider: 'Anthropic' },
+  ];
+
+  // events are CustomEvents on the element (they do not bubble)
+  workspace.addEventListener('conversationselect', (e) => console.log('selected conversation:', e.detail.id));
+  workspace.addEventListener('submit', (e) => console.log('user sent:', e.detail.value));
+  workspace.addEventListener('sidebartoggle', (e) => console.log('sidebar collapsed:', e.detail.collapsed));
+</script>`;
+
+const SOLID_SNIPPET = `import '@kitnai/chat/elements'; // registers the custom elements
+import { onMount } from 'solid-js';
+import type { ConversationSummary, ModelOption } from '@kitnai/chat';
+import type { ChatMessage } from '@kitnai/chat/elements';
+
+function Workspace() {
+  let el: HTMLElement & {
+    conversations?: ConversationSummary[];
+    messages?: ChatMessage[];
+    models?: ModelOption[];
+    activeId?: string;
+  };
+  const conversations: ConversationSummary[] = [
+    {
+      id: '1', title: 'Web component architecture',
+      scope: { type: 'document' }, messageCount: 12,
+      lastMessageAt: '2026-06-13T15:30:00Z', updatedAt: '2026-06-13T15:30:00Z',
+    },
+  ];
+  const messages: ChatMessage[] = [
+    { id: 'm1', role: 'user', content: 'How do I drop the whole chat app in with one tag?' },
+    { id: 'm2', role: 'assistant', content: 'Use <kitn-chat-workspace> — set conversations, messages, and models as properties.' },
+  ];
+  onMount(() => {
+    el.conversations = conversations;
+    el.messages = messages;
+    el.activeId = '1';
+    el.addEventListener('conversationselect', (e) => console.log('selected:', e.detail.id));
+    el.addEventListener('submit', (e) => console.log('user sent:', e.detail.value));
+    el.addEventListener('sidebartoggle', (e) => console.log('sidebar collapsed:', e.detail.collapsed));
+  });
+  return (
+    <kitn-chat-workspace
+      ref={el}
+      style={{ display: 'block', height: '100vh' }}
+    />
+  );
+}`;
+
+const meta = {
+  title: 'Web Components/kitn-chat-workspace',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-chat-workspace>` is the full chat shell as a single **web component** — a resizable split layout with a collapsible conversation list on the left and a full message thread on the right, all isolated in **Shadow DOM**. SolidJS is bundled in, so the host needs nothing.',
+          '**When to use:** dropping an entire chat application shell into a non-Solid app (React, Vue, Svelte, plain HTML), or anywhere you want zero style conflicts and a ready-made list+chat layout. If you *are* in SolidJS and want fine-grained control, compose the `ConversationList` and `ChatThread` primitives directly.',
+          '**How to use:** register once with `import \'@kitnai/chat/elements\'`, set rich data as JS **properties** (`el.conversations = [...]`, `el.messages = [...]`, `el.models = [...]`), and listen for **CustomEvents** (`conversationselect`, `submit`, `sidebartoggle`, `newchat`) directly on the element.',
+          '**Placement:** as a full-page surface or large panel. Give it an explicit height (e.g. `height: 100vh`). The sidebar is drag-resizable and can be collapsed via the toggle button in its header.',
+          '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;
+
+export default meta;
+type Story = StoryObj;
+
+/** The element used the plain-HTML / any-framework way. */
+export const Default: Story = {
+  render: () => <WorkspaceElement />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** The same element used inside a SolidJS component (properties via `ref` + `onMount`, events via `addEventListener`). */
+export const InSolidJS: Story = {
+  name: 'In SolidJS',
+  render: () => <WorkspaceElement />,
+  parameters: { docs: { source: { code: SOLID_SNIPPET, language: 'tsx' } } },
+};