@kitnai/chat 0.7.0 → 0.8.0

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

@@ -1,16 +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 { ElementSpec } from '../stories/docs/element-spec';
-import { argTypesFor } from '../stories/docs/element-controls';
+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>;
     }
   }
 }
@@ -42,7 +41,7 @@ interface PromptInputEl extends HTMLElement {
   attachments?: AttachmentData[];
 }
 
-/** Live demo of the actual `<kitn-prompt-input>` custom element (Shadow DOM and all). */
+/** 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(() => {
@@ -68,7 +67,7 @@ function PromptInputElement(props: { search?: boolean; voice?: boolean; attachme
     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' }}
     />
@@ -76,7 +75,7 @@ function PromptInputElement(props: { search?: boolean; voice?: boolean; attachme
 }
 
 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
@@ -109,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)}
@@ -120,21 +119,19 @@ function Composer() {
 }`;
 
 const meta = {
-  title: 'Web Components/kitn-prompt-input',
+  title: 'Web Components/kc-prompt-input',
   tags: ['autodocs'],
-  argTypes: argTypesFor('kitn-prompt-input'),
+  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;
@@ -165,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';
@@ -183,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';
@@ -204,8 +201,3 @@ export const WithAttachments: Story = {
   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/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[] };
@@ -56,7 +56,7 @@ interface Events {
   voice: Record<string, never>;
 }
 
-defineKitnElement<Props, Events>('kitn-prompt-input', {
+defineWebComponent<Props, Events>('kc-prompt-input', {
   value: undefined,
   placeholder: 'Send a message...',
   disabled: false,

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

@@ -1,8 +1,7 @@
 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';
+import { argTypesFor, specDescription } from '../stories/docs/element-controls';
 
 type Item = string | { label: string; value?: string };
 
@@ -11,7 +10,7 @@ declare module 'solid-js' {
   // eslint-disable-next-line @typescript-eslint/no-namespace
   namespace JSX {
     interface IntrinsicElements {
-      'kitn-prompt-suggestions': JSX.HTMLAttributes<HTMLElement> & {
+      'kc-suggestions': JSX.HTMLAttributes<HTMLElement> & {
         variant?: string;
         size?: string;
         block?: boolean | string;
@@ -27,7 +26,7 @@ const suggestions: Item[] = [
   "What's deferred?",
 ];
 
-/** Render `<kitn-prompt-suggestions>` with `suggestions` set as a property. */
+/** Render `<kc-suggestions>` with `suggestions` set as a property. */
 function SuggestionsElement(props: { suggestions: Item[]; variant?: string; size?: string; block?: boolean; highlight?: string }) {
   let el: (HTMLElement & { suggestions?: Item[] }) | undefined;
   onMount(() => {
@@ -39,7 +38,7 @@ function SuggestionsElement(props: { suggestions: Item[]; variant?: string; size
     });
   });
   return (
-    <kitn-prompt-suggestions
+    <kc-suggestions
       ref={(e) => (el = e as HTMLElement)}
       variant={props.variant}
       size={props.size}
@@ -51,7 +50,7 @@ function SuggestionsElement(props: { suggestions: Item[]; variant?: string; size
 }
 
 const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
-<kitn-prompt-suggestions id="suggs" variant="outline"></kitn-prompt-suggestions>
+<kc-suggestions id="suggs" variant="outline"></kc-suggestions>
 
 <script type="module">
   import '@kitnai/chat/elements';   // registers the custom elements
@@ -62,20 +61,18 @@ const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
 </script>`;
 
 const meta = {
-  title: 'Web Components/kitn-prompt-suggestions',
+  title: 'Web Components/kc-suggestions',
   tags: ['autodocs'],
-  argTypes: argTypesFor('kitn-prompt-suggestions'),
+  argTypes: argTypesFor('kc-suggestions'),
   parameters: {
     layout: 'fullscreen',
     docs: {
-      description: {
-        component: [
-          '`<kitn-prompt-suggestions>` is the framework-agnostic **web component** for a row (or list) of clickable suggestion chips — starter prompts or follow-ups — isolated in **Shadow DOM**.',
+      description: specDescription('kc-suggestions', [
+          '`<kc-suggestions>` is the framework-agnostic **web component** for a row (or list) of clickable suggestion chips — starter prompts or follow-ups — isolated in **Shadow DOM**.',
           '**When to use:** offering the user quick prompts to click instead of type, usually above an input. In SolidJS, use the `PromptSuggestion` primitive.',
           "**How to use:** register once with `import '@kitnai/chat/elements'`, set the `suggestions` **property** (strings, or `{ label, value }` when the displayed text differs from the emitted value), choose a `variant` and `size` (`sm` | `md` | `lg`; pills default to `lg`), optionally add the `block` flag for full-width rows or a `highlight` substring to emphasize, and listen for the `select` **CustomEvent**.",
           'See the **Code** tab for HTML usage.',
-        ].join('\n\n'),
-      },
+        ]),
     },
   },
 } satisfies Meta;
@@ -83,12 +80,6 @@ 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" />,
@@ -121,7 +112,7 @@ export const WithHighlightedSearch: Story = {
   parameters: {
     docs: {
       source: {
-        code: `<kitn-prompt-suggestions id="suggs" highlight="Solid"></kitn-prompt-suggestions>
+        code: `<kc-suggestions id="suggs" highlight="Solid"></kc-suggestions>
 
 <script type="module">
   import '@kitnai/chat/elements';
@@ -156,9 +147,9 @@ export const Sizes: Story = {
     docs: {
       source: {
         code: `<!-- default pill -->
-<kitn-prompt-suggestions variant="outline"></kitn-prompt-suggestions>
+<kc-suggestions variant="outline"></kc-suggestions>
 <!-- smaller pill -->
-<kitn-prompt-suggestions variant="outline" size="sm"></kitn-prompt-suggestions>`,
+<kc-suggestions variant="outline" size="sm"></kc-suggestions>`,
         language: 'html',
       },
     },

package/src/elements/prompt-suggestions.tsx

@@ -1,5 +1,5 @@
 import { For } from 'solid-js';
-import { defineKitnElement } from './define';
+import { defineWebComponent } from './define';
 import { PromptSuggestion } from '../components/prompt-suggestion';
 
 type Item = string | { label: string; value?: string };
@@ -19,7 +19,7 @@ interface Props extends Record<string, unknown> {
   highlight?: string;
 }
 
-/** Events fired by `<kitn-prompt-suggestions>`. */
+/** Events fired by `<kc-suggestions>`. */
 interface Events {
   /** A suggestion was clicked. */
   select: { value: string };
@@ -29,11 +29,11 @@ const labelOf = (s: Item) => (typeof s === 'string' ? s : s.label);
 const valueOf = (s: Item) => (typeof s === 'string' ? s : s.value ?? s.label);
 
 /**
- * `<kitn-prompt-suggestions>` — a row/list of suggestion chips. Data via the
+ * `<kc-suggestions>` — a row/list of suggestion chips. Data via the
  * `suggestions` property; `variant`/`block`/`highlight` attributes; emits
  * `select`.
  */
-defineKitnElement<Props, Events>('kitn-prompt-suggestions', {
+defineWebComponent<Props, Events>('kc-suggestions', {
   suggestions: [],
   variant: 'outline',
   size: undefined,

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

@@ -1,15 +1,14 @@
 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';
+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-reasoning': JSX.HTMLAttributes<HTMLElement>;
+      'kc-reasoning': JSX.HTMLAttributes<HTMLElement>;
     }
   }
 }
@@ -17,7 +16,7 @@ declare module 'solid-js' {
 const sampleText =
   'First I parse the request, then I plan the steps, then I execute and verify each one before responding.';
 
-/** Render the actual `<kitn-reasoning>` custom element with a `text` property. */
+/** Render the actual `<kc-reasoning>` custom element with a `text` property. */
 function ReasoningElement(props: { text: string; streaming?: boolean }) {
   let el: (HTMLElement & { text?: string; streaming?: boolean }) | undefined;
   onMount(() => {
@@ -27,12 +26,12 @@ function ReasoningElement(props: { text: string; streaming?: boolean }) {
     }
   });
   return (
-    <kitn-reasoning ref={(e) => (el = e as HTMLElement)} style={{ display: 'block', padding: '16px', 'max-width': '720px' }} />
+    <kc-reasoning 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-reasoning id="reason" label="Reasoning"></kitn-reasoning>
+<kc-reasoning id="reason" label="Reasoning"></kc-reasoning>
 
 <script type="module">
   import '@kitnai/chat/elements';   // registers the custom elements
@@ -46,20 +45,18 @@ const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
 </script>`;
 
 const meta = {
-  title: 'Web Components/kitn-reasoning',
+  title: 'Web Components/kc-reasoning',
   tags: ['autodocs'],
-  argTypes: argTypesFor('kitn-reasoning'),
+  argTypes: argTypesFor('kc-reasoning'),
   parameters: {
     layout: 'fullscreen',
     docs: {
-      description: {
-        component: [
-          '`<kitn-reasoning>` is the framework-agnostic **web component** for a collapsible reasoning/thinking block that auto-expands while a thought is `streaming`, isolated in **Shadow DOM**.',
+      description: specDescription('kc-reasoning', [
+          '`<kc-reasoning>` is the framework-agnostic **web component** for a collapsible reasoning/thinking block that auto-expands while a thought is `streaming`, isolated in **Shadow DOM**.',
           '**When to use:** surfacing model chain-of-thought in a non-Solid app. In SolidJS, compose the `Reasoning` primitives directly.',
           "**How to use:** register once with `import '@kitnai/chat/elements'`, set the body via the `text` **property**, set the `streaming` flag while it streams in, optionally drive the controlled `open` property, and listen for the `openchange` **CustomEvent**.",
           'See the **Code** tab for HTML usage.',
-        ].join('\n\n'),
-      },
+        ]),
     },
   },
 } satisfies Meta;
@@ -67,12 +64,6 @@ 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/reasoning.tsx

@@ -1,4 +1,4 @@
-import { defineKitnElement } from './define';
+import { defineWebComponent } from './define';
 import { Reasoning, ReasoningTrigger, ReasoningContent } from '../components/reasoning';
 import { ChatConfig, useChatConfig } from '../primitives/chat-config';
 
@@ -16,18 +16,18 @@ interface Props extends Record<string, unknown> {
   markdown?: boolean;
 }
 
-/** Events fired by `<kitn-reasoning>`. */
+/** Events fired by `<kc-reasoning>`. */
 interface Events {
   /** Open state changed (via the trigger or streaming auto-open). */
   openchange: { open: boolean };
 }
 
 /**
- * `<kitn-reasoning>` — a collapsible reasoning/thinking block that auto-expands
+ * `<kc-reasoning>` — a collapsible reasoning/thinking block that auto-expands
  * while `streaming`. Text via the `text` property; `markdown`/`streaming` flags;
  * `open` is a controlled property; emits `openchange`.
  */
-defineKitnElement<Props, Events>('kitn-reasoning', {
+defineWebComponent<Props, Events>('kc-reasoning', {
   text: '',
   label: 'Reasoning',
   open: undefined,

package/src/elements/register.ts

@@ -21,7 +21,7 @@ import './chat-scope-picker';
 // Phase 3 — input ecosystem
 // (NB: SlashCommand is context-bound to PromptInput — it observes the input
 //  value via usePromptInput() — so it is NOT a standalone element. It will fold
-//  into <kitn-prompt-input> as a `slash-commands` property in a later pass.)
+//  into <kc-prompt-input> as a `slash-commands` property in a later pass.)
 import './prompt-suggestions';
 import './file-upload';
 import './voice-input';
@@ -35,6 +35,16 @@ import './source';
 import './response-stream';
 import './empty';
 import './chain-of-thought';
+import './resizable';
+import './file-tree';
+import './artifact';
+// Generative-UI cards (Card Contract)
+import './card';
+import './form';
+import './link-card';
+import './embed';
+import './confirm-card';
+import './task-list-card';
 
 export type { ChatMessage, ChatMessageAction } from './chat-types';
 export { configureCodeHighlighting, isCodeHighlightingEnabled } from '../primitives/highlighter';

package/src/elements/resizable.stories.tsx

@@ -0,0 +1,200 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { createSignal, type JSX } 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 {
+      'kc-resizable': JSX.HTMLAttributes<HTMLElement> & { orientation?: string };
+      'kc-resizable-item': JSX.HTMLAttributes<HTMLElement> & {
+        size?: string; min?: string; max?: string; locked?: boolean | string; hidden?: boolean | string;
+      };
+    }
+  }
+}
+
+/** A labelled placeholder pane so the layout is visible in stories. */
+function Pane(props: { label: string; tone?: 'muted' | 'plain' }) {
+  return (
+    <div
+      style={{
+        height: '100%',
+        display: 'flex',
+        'align-items': 'center',
+        'justify-content': 'center',
+        padding: '16px',
+        background: props.tone === 'plain' ? 'transparent' : 'var(--color-muted, #f4f4f5)',
+        color: 'var(--color-muted-foreground, #71717a)',
+        'font-size': '13px',
+      }}
+    >
+      {props.label}
+    </div>
+  );
+}
+
+/** A bordered, sized frame the group fills. */
+function Frame(props: { children: JSX.Element; tall?: boolean }) {
+  return (
+    <div
+      style={{
+        height: props.tall ? '384px' : '256px',
+        width: '100%',
+        'max-width': '768px',
+        border: '1px solid var(--color-border, #e4e4e7)',
+        'border-radius': '8px',
+        overflow: 'hidden',
+      }}
+    >
+      {props.children}
+    </div>
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kc-resizable orientation="horizontal" style="display:block;height:400px">
+  <kc-resizable-item size="25%" min="160px"> ...list... </kc-resizable-item>
+  <kc-resizable-item> ...chat... </kc-resizable-item>
+  <kc-resizable-item size="30%"> ...preview... </kc-resizable-item>
+</kc-resizable>
+
+<script type="module">
+  import '@kitnai/chat/elements'; // registers the custom elements
+  document.querySelector('kc-resizable')
+    .addEventListener('change', (e) => console.log(e.detail.sizes));
+</script>`;
+
+const meta = {
+  title: 'Web Components/kc-resizable',
+  tags: ['autodocs'],
+  argTypes: argTypesFor('kc-resizable'),
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: specDescription('kc-resizable', [
+        '`<kc-resizable>` is the framework-agnostic **web component** for a composable, resizable multi-panel layout (up to **3** `<kc-resizable-item>` panels) with **auto-inserted draggable dividers** — isolated in **Shadow DOM**.',
+        '**When to use:** to compose an app shell out of slotted regions without hand-wiring panels and handles — e.g. `list | chat | preview`. In SolidJS, use the `Resizable` convenience (UI/Resizable) directly.',
+        "**How to use:** register once with `import '@kitnai/chat/elements'`, set `orientation` (`horizontal` row / `vertical` column), and put a `<kc-resizable-item>` per panel. Each item carries `size` (px or %, e.g. `\"280px\"` or `\"25%\"`), `min`/`max`, `locked` (fixed size + non-draggable neighbour), and `hidden` (drops the panel + its divider). Listen for the **`change`** event (`detail.sizes`, percent).",
+        '**Placement:** the layout spine for compose-your-own-chat shells — sidebar + conversation, conversation + inspector, or a three-up list/chat/preview.',
+        'See the **Code** tab for HTML usage.',
+      ]),
+    },
+  },
+  args: { orientation: 'horizontal' },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** Interactive playground — flip orientation, then drag the dividers. */
+export const Playground: Story = {
+  render: (args: { orientation?: string }) => (
+    <Frame>
+      <kc-resizable orientation={args.orientation ?? 'horizontal'}>
+        <kc-resizable-item size="25%" min="120px"><Pane label="List" /></kc-resizable-item>
+        <kc-resizable-item><Pane label="Chat" tone="plain" /></kc-resizable-item>
+      </kc-resizable>
+    </Frame>
+  ),
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** Two panels: a sized list beside a flexible chat. */
+export const ListChat: Story = {
+  name: 'Sidebar + chat',
+  render: () => (
+    <Frame>
+      <kc-resizable orientation="horizontal">
+        <kc-resizable-item size="28%" min="140px" max="50%"><Pane label="List" /></kc-resizable-item>
+        <kc-resizable-item><Pane label="Chat" tone="plain" /></kc-resizable-item>
+      </kc-resizable>
+    </Frame>
+  ),
+};
+
+/** Three panels, two draggable dividers. */
+export const ListChatPreview: Story = {
+  name: 'List + chat + preview',
+  render: () => (
+    <Frame>
+      <kc-resizable orientation="horizontal">
+        <kc-resizable-item size="22%" min="120px"><Pane label="List" /></kc-resizable-item>
+        <kc-resizable-item><Pane label="Chat" tone="plain" /></kc-resizable-item>
+        <kc-resizable-item size="30%" min="160px"><Pane label="Preview" /></kc-resizable-item>
+      </kc-resizable>
+    </Frame>
+  ),
+};
+
+/** A locked, fixed-px sidebar — its divider is a static (non-draggable) separator. */
+export const LockedSidebar: Story = {
+  name: 'Locked sidebar',
+  render: () => (
+    <Frame>
+      <kc-resizable orientation="horizontal">
+        <kc-resizable-item size="240px" locked><Pane label="Locked sidebar (240px)" /></kc-resizable-item>
+        <kc-resizable-item><Pane label="Chat" tone="plain" /></kc-resizable-item>
+      </kc-resizable>
+    </Frame>
+  ),
+};
+
+/** Stacked top/bottom split. */
+export const Vertical: Story = {
+  name: 'Vertical split',
+  render: () => (
+    <Frame tall>
+      <kc-resizable orientation="vertical">
+        <kc-resizable-item size="40%" min="80px"><Pane label="Top" /></kc-resizable-item>
+        <kc-resizable-item><Pane label="Bottom" tone="plain" /></kc-resizable-item>
+      </kc-resizable>
+    </Frame>
+  ),
+};
+
+/** Toggle the preview panel — its divider drops and the rest reflow. */
+export const HiddenToggle: Story = {
+  name: 'Show / hide a panel',
+  render: () => {
+    const [showPreview, setShowPreview] = createSignal(true);
+    let previewItem: HTMLElement | undefined;
+    const toggle = () => {
+      setShowPreview((v) => !v);
+      // Drive the boolean attribute directly so the group's MutationObserver
+      // re-lays out (Solid sets the `hidden` IDL property, which doesn't reflect
+      // to the attribute on a custom element).
+      if (previewItem) {
+        if (showPreview()) previewItem.removeAttribute('hidden');
+        else previewItem.setAttribute('hidden', '');
+      }
+    };
+    return (
+      <div style={{ display: 'flex', 'flex-direction': 'column', gap: '8px' }}>
+        <button
+          type="button"
+          onClick={toggle}
+          style={{
+            'align-self': 'flex-start',
+            padding: '4px 12px',
+            'font-size': '13px',
+            border: '1px solid var(--color-border, #e4e4e7)',
+            'border-radius': '6px',
+            cursor: 'pointer',
+          }}
+        >
+          {showPreview() ? 'Hide preview' : 'Show preview'}
+        </button>
+        <Frame>
+          <kc-resizable orientation="horizontal">
+            <kc-resizable-item size="24%" min="120px"><Pane label="List" /></kc-resizable-item>
+            <kc-resizable-item><Pane label="Chat" tone="plain" /></kc-resizable-item>
+            <kc-resizable-item ref={(e) => (previewItem = e as HTMLElement)} size="30%"><Pane label="Preview" /></kc-resizable-item>
+          </kc-resizable>
+        </Frame>
+      </div>
+    );
+  },
+};